How It Works

Option A: Polling

Submit a job, check back periodically, download when ready. Simple and reliable.

1. POST /tts/submit       →  { jobId, status: "queued" }
2. GET  /tts/status/:jobId →  { status: "processing" }
3. GET  /tts/status/:jobId →  { status: "done", downloadUrl: "..." }
4. Download MP3 from downloadUrl (no auth needed)

Option B: Webhook Callback

Provide a callbackUrl and we'll POST the results to your server when the job completes. No polling needed.

1. POST /tts/submit  →  { jobId, status: "queued" }
   body: { text, voice, langs, callbackUrl: "https://your-server.com/webhook" }

2. (your app does other work — no polling needed)

3. POST your callbackUrl ← AethonVoice calls you
   {
     "jobId": "Xk9mP2qR7vNw",
     "status": "done",
     "downloadUrl": "https://storage.googleapis.com/...",
     "durationMs": 2100
   }

4. Download MP3 from downloadUrl (no auth needed)

Best for batch jobs and server-to-server integrations. You can still poll GET /tts/status/:jobId as a fallback.

If generation fails, you still receive a callback — the payload carries a top-level error string so you don't have to walk the items map:

{
  "batchId": "Bt9xK2pL...",
  "status": "error",
  "error": "All 3 items failed",
  "items": { /* per-item status + error */ }
}

Credits are only debited for items that successfully returned audio — failed items are never charged.

Quick Start

curl -X POST https://aethon.lab.ai/api/tts/submit \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "text": "Welcome to AethonVoice.",
    "voice": "aris",
    "langs": ["en"]
  }'

{
  "jobId": "Xk9mP2qR7vNw",
  "status": "queued"
}

curl https://aethon.lab.ai/api/tts/status/Xk9mP2qR7vNw \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "jobId": "Xk9mP2qR7vNw",
  "status": "done",
  "downloadUrl": "https://storage.googleapis.com/...",
  "durationMs": 2100
}

Polling Tips

Endpoints

What You Need

How It Works

Once connected, you talk to your AI assistant in plain language:

Text

Plain text in any of the 21 supported languages (24 locale variants). Mixed-language text is handled automatically.

Language Tags

For explicit control over language boundaries, wrap portions in XML-style tags:

<ja>聞いてください</ja> This is English <th>สวัสดีครับ</th>

Tags are optional. Tagged portions use the specified language. Untagged portions are split automatically by character range detection. You can mix tagged and untagged text freely.

When to use tags: When languages share the same script (e.g., Chinese and Japanese both use CJK characters). For most other language pairs, automatic detection works without tags.

Paralinguistic Tags

Insert natural sound effects inline:

I was thinking [pause] maybe we should [laugh] just go for it

Tags work with both API and MCP Server.

Voices

Additional Request Fields