🎙️ Voice & TTS API Reference

The LuxurAI Voice API provides programmatic access to 322 neural voice models across 142 global languages and regional locales. It supports instant speech synthesis, voice catalog discovery, audio streaming, and automatic language detection.

All requests require authentication with an active API Key (lxr_v1_...).

---

🔑 Authentication

Include your API key in the Authorization header:

Authorization: Bearer lxr_v1_your_api_key_here

To create or manage API keys, visit your account dashboard at luxurai.in -> Dashboard -> API Keys.

---

🔌 Endpoints

1. List Available Neural Voices

Query the voice catalog with optional language/locale and gender filtering.

• Endpoint: GET /api/tts/voices
• Query Parameters:
  • lang (optional, string): Filter by language code or locale (e.g. hi, en, es, ja, zh, hi-IN, en-US).
  • gender (optional, string): Filter by gender (female or male).
• Headers:

  Authorization: Bearer lxr_v1_your_api_key_here

• Success Response (200 OK):

  [
    {
      "name": "hi-IN-SwaraNeural",
      "gender": "Female",
      "locale": "hi-IN",
      "locale_name": "Hindi (India)",
      "friendly_name": "Microsoft Swara Online (Natural) - Hindi (India)"
    },
    {
      "name": "hi-IN-MadhurNeural",
      "gender": "Male",
      "locale": "hi-IN",
      "locale_name": "Hindi (India)",
      "friendly_name": "Microsoft Madhur Online (Natural) - Hindi (India)"
    }
  ]

---

2. Synthesize Speech (/api/tts/speak)

Generate neural voice audio from text with sub-second latency.

• Endpoint: POST /api/tts/speak
• Request Headers:

  Content-Type: application/json
  Authorization: Bearer lxr_v1_your_api_key_here

• Request Body:

  {
    "text": "Hello, welcome to LuxurAI! How can I assist you today?",
    "voice": "en-US-JennyNeural",
    "gender": "female",
    "lang": "en",
    "speed": 1.0,
    "store_voice": true
  }

Request Parameters

Parameter	Type	Required	Description
text	string	Yes	Text to convert to speech (HTML/Markdown stripped automatically)
voice	string	No	Exact neural voice identifier (e.g. en-US-JennyNeural, hi-IN-SwaraNeural)
gender	string	No	Preferred voice gender: "female" or "male" (default: "female")
lang	string	No	Language code or "auto" for automatic script detection
speed	float	No	Playback speed multiplier from 0.5 to 2.0 (default: 1.0)
store_voice	boolean	No	Set false for Ghost Mode (does not store text or audio in history)

Response (200 OK)

Returns raw MP3 audio bytes with metadata embedded in HTTP response headers:

• Content-Type: audio/mpeg
• Response Headers:
  • X-TTS-Engine: Engine used (e.g. CloudflareWorker-EdgeTTS or EdgeTTS-Direct)
  • X-Audio-Duration: Duration of the synthesized audio in seconds (e.g. 3.420)
  • X-LC-Charged: Lunar Coins deducted based on audio duration (e.g. 0.019)
  • X-LC-Balance: Remaining Lunar Coins balance on the account
  • X-TTS-Cache: HIT if served from the zero-latency in-memory cache, MISS otherwise
  • X-Audio-URL: Permanent cloud URL of the saved audio file (if store_voice=true)

---

3. Service Health Check

Verify the operational health and readiness of the voice synthesis engines.

• Endpoint: GET /api/tts/health
• Success Response (200 OK):

  {
    "status": "online",
    "engine": "Hybrid (CloudflareWorker-Primary + EdgeTTS-Direct)",
    "edge_tts_ready": true,
    "total_voices": 322,
    "total_languages": 142,
    "default_voice": "en-US-ChristopherNeural"
  }

---

🐍 Python Example (Direct HTTP)

import httpx

API_KEY = "lxr_v1_your_api_key_here"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "text": "LuxurAI voice generation is blazing fast and natural.",
    "gender": "female",
    "lang": "en"
}

with httpx.Client() as client:
    response = client.post("https://luxurai.in/api/tts/speak", json=payload, headers=headers)
    
    if response.status_code == 200:
        duration = response.headers.get("X-Audio-Duration")
        charged = response.headers.get("X-LC-Charged")
        print(f"Generated {duration}s of audio. Cost: {charged} LC.")
        
        with open("output.mp3", "wb") as f:
            f.write(response.content)
        print("Saved to output.mp3")
    else:
        print("Error:", response.status_code, response.text)