How It Works

Option A: Polling

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

1. POST /submit                →  { batchId, status: "queued" }
2. GET  /batch-status/:batchId →  { status: "processing" }
3. GET  /batch-status/:batchId →  { status: "done", items: { item0: { 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 /submit  →  { batchId, 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
   {
     "batchId": "Xk9mP2qR7vNw",
     "status": "done",
     "items": {
       "item0": { "status": "done", "downloadUrl": "https://storage.googleapis.com/...", "durationMs": 2100 }
     },
     "callbackRef": null
   }

4. Download MP3 from downloadUrl (no auth needed)

Best for batch jobs and server-to-server integrations. You can still poll GET /batch-status/:batchId as a fallback. Your endpoint should answer 2xx within 10 seconds; failed deliveries are retried (7 attempts over ~9 hours).

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://api.aethon.lab.ai/v1/submit \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "text": "Welcome to AethonVoice.",
    "voice": "aris",
    "langs": ["en-US"]
  }'

{
  "batchId": "Xk9mP2qR7vNw",
  "status": "queued",
  "gpu": "L4"
}

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

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

Polling Tips

Endpoints

All paths are relative to https://api.aethon.lab.ai/v1.

What You Need

How It Works

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

Text

Write text the way you would for a human reader, in any of the 19 supported languages. Numbers, dates, times, prices, percentages, units and phone numbers are read aloud correctly for each language ($2.50, 12:30, 24 GB, 68.5%). A line break becomes a short pause (0.7–1.1 s). Long text is fine — it is split internally and joined into one MP3.

Mixed-Language Text

List every language in the text in langs; the first one is the main language. The service finds which part is which language in one of two ways.

1. Automatic (no tags)

Languages are recognized by their writing system, so this works whenever each language in langs has its own: Thai + English, Japanese + English, Russian + English, Arabic + French, Korean + Chinese …

Two languages from the same row (Spanish + English, Chinese + Japanese kanji) look the same to the service: all of that text is treated as the language listed first. Use tags for the other one.

2. Tags

Wrap a part in <code>…</code> to say its language. Tags always win and are removed before speech.

La reunión se llama <en>Weekly Sync</en> y empieza a las 9.

• <en> means the English you listed (en-US or en-GB), <zh> the Chinese you listed; otherwise en-US / zh-CN.
• A tag's language must be in langs, and tags must be closed and not nested — otherwise 400.
• Numbers are read in the main language, even next to a foreign word or unit (24 GB in a Thai sentence is read in Thai). To have a number read in another language, put it inside a tag.

Non-Verbal Sounds

Put a tag in square brackets where the voice should make a sound instead of words. The voice makes it in its own character, in any language.

I told him the whole story, [laughter] and he still didn't believe me. [sigh]

Write tags exactly as listed, in lowercase; other bracketed text is read as ordinary text. For a pause, use a line break.

Voices

Additional Request Fields