aethexDocs
Dashboard

API Reference

Text-To-Speech (TTS) API

Convert text into speech audio.Single-shot. POST /tts synthesizes in one request. Returns a complete WAV file, or set streaming: true to receive chunked PCM16 as soon as the model emits it.Dedicated stream. POST /tts/stream is the streaming-only path; equivalent to POST /tts with streaming: true. Useful when you want a fixed URL for the streaming case.Batch. POST /tts/batch queues up to 50 texts for background synthesis. Poll GET /tts/batch/{batch_id} or pass a webhook_url to be notified. Each item comes back as a signed download URL.Billing. Per character. For streaming, charges only land when the stream finishes successfully; client disconnects before audio starts are not billed.

Base URL
https://api.aethexai.com/api/v1
Endpoints
4
Scopes
tts:use
POST/tts

Synthesize text to a WAV file, or stream raw PCM chunks with `streaming: true`.

Synthesize Speech

Converts text to audio in a single request.WAV mode. The default. The response body is a complete audio/wav file. The header carries X-Sample-Rate: 24000.Streaming mode. Set streaming: true for real-time audio, ready to play as the model speaks it. The response is audio/pcm with Transfer-Encoding: chunked and X-Encoding: pcm16. The body is contiguous little-endian signed 16-bit PCM at 24 kHz, mono, with no header or framing. Read the chunks in order and feed them straight into a 24 kHz mono playback buffer.Output format. Audio is 24 kHz, 16-bit, mono. WAV mode returns RIFF-headered audio/wav; streaming mode returns raw audio/pcm. Other codecs and sample rates are not currently exposed.

Request body

4
  • textstringrequired

    Text to synthesize. 1–650 characters per request; every character counts toward billing. Use POST /tts/batch for longer scripts.

  • languagestringoptional

    Currently supports english (default) and french; more languages are on the roadmap.

  • voice_idstringoptional

    Voice identifier from GET /voices. Omit this field to use the deployment default voice; legacy clients may pass default with the same effect.

  • streamingbooleanoptional

    Set true for chunked PCM16 streaming instead of a complete WAV file. Default false.

Errors

4
404Voice not linked to an active TTS model

The voice_id resolves but has no active TTS model bound to it. The server returns the detail string "Voice not linked to an active TTS model" verbatim — match on that string.

Check the ID with GET /voices, or omit voice_id to use the default.

413Text too long

The text is over the 650-character synchronous TTS safety cap. The request returns 413 before synthesis starts.

Use POST /tts/batch for long-form text, or split the text at sentence boundaries and synthesize shorter realtime chunks.

422Validation error

text is empty or longer than the schema ceiling, language is not english/french, or one word in text is too long to speak (a long code, token or URL with no spaces). The error field gives the reason.

Send 1–650 characters of text and a supported language code, and write long codes with spaces between groups. For longer copy, use POST /tts/batch.

503TTS not ready

The synthesis service is starting up or scaling.

Retry after a short delay. A freshly-deployed voice may take a minute or two to warm up.

POST/tts/stream

Dedicated streaming endpoint; same wire format as `POST /tts` with `streaming: true`.

Stream Synthesis

Streaming-only synthesis. Returns chunked PCM16 audio over a single HTTP response: little-endian signed 16-bit at 24 kHz mono, no header, no length prefix. Same headers and same latency profile as POST /tts with streaming: true; use this path when you want a fixed URL for the streaming case. Billing only fires when the stream completes, so client disconnects before the first audio frame are not charged.

Request body

3
  • textstringrequired

    Text to synthesize. 1–650 characters per stream request.

  • languagestringoptional

    Currently supports english (default) and french; more languages are on the roadmap.

  • voice_idstringoptional

    Voice identifier from GET /voices. Omit this field to use the default voice; legacy clients may pass default with the same effect.

Errors

4
404Voice not linked to an active TTS model

The voice_id resolves but has no active TTS model bound to it. The server returns the detail string "Voice not linked to an active TTS model" verbatim — match on that string.

Check the ID with GET /voices, or omit voice_id.

413Text too long

The text is over the 650-character synchronous TTS safety cap. The request returns 413 before synthesis starts.

Use POST /tts/batch for long-form generation, or split the text into shorter chunks and stream them sequentially.

422Validation error

text is empty or longer than the schema ceiling, language is not english/french, or one word in text is too long to speak (a long code, token or URL with no spaces). The error field gives the reason.

Use 1–650 characters and a supported language code, and write long codes with spaces between groups. For longer copy, use POST /tts/batch.

503TTS not ready

The synthesis service is starting up or scaling.

Retry after a short delay.

POST/tts/batch

Submit up to 50 texts for background synthesis. Poll for signed download URLs.

Batch Synthesis

Queues a list of texts for asynchronous synthesis. Returns immediately with a batch_id and status: "queued". Poll GET /tts/batch/{batch_id} for progress, or pass a webhook_url to receive a callback when the batch completes. Long items are split internally into realtime-safe chunks before inference, then returned as one WAV per original item. Per-item billing only applies to successfully synthesized items.Webhook fields. webhook_status is null when no webhook_url was supplied. When a webhook is registered, it transitions through pending → delivered, failed, or unsafe (the URL resolved to a private or blocked host at delivery time). The companion fields webhook_last_error, webhook_last_attempt_at, and webhook_delivered_at are populated only when a webhook is in play.

Request body

4
  • itemsobject[]required

    Array of items to synthesize, 1–50 entries. Each item is { text: string, language?: "english" | "french" }. Per-item language overrides the batch default. Each text must be 1–3000 characters; the worker splits long items into 650-character-or-smaller backend requests.

  • languagestringoptional

    Default language for items that do not set their own. Currently english (default) or french; more on the roadmap.

  • voice_idstringoptional

    Voice identifier from GET /voices, applied to every item in the batch. Omit this field to use the default voice; legacy clients may pass default with the same effect. No per-item override; submit separate batches for different voices.

  • webhook_urlstringoptional

    HTTPS URL invoked when the batch reaches a terminal state. The payload is the same shape as GET /tts/batch/{batch_id} and is signed with your account webhook secret.

Errors

3
404Voice not linked to an active TTS model

The voice_id resolves but has no active TTS model bound to it. Checked at submit time so a failed voice fails fast, not deep in the worker. The server returns the detail string "Voice not linked to an active TTS model" verbatim — match on that string.

Check the ID with GET /voices, or omit voice_id.

422Validation error

items is empty or longer than 50 entries; an item's text is empty or over the schema ceiling; or language is not english/french.

Send 1–50 items, each with 1–3000 characters of text, and a supported language code.

503Service temporarily unavailable

We're at capacity right now.

Retry the request. If it persists, contact our team at [email protected].

GET/tts/batch/:batch_id

Poll a batch; returns signed download URLs for every completed item.

Get Batch Status

Returns the current status and per-item results for a batch. status cycles through queued → running → completed (or failed if every item errored). The results array gets one entry per item once processed; audio_url is a signed download URL that expires after a short window (default 15 minutes), so re-poll for fresh URLs as needed. Failed items carry an error string instead of audio_url.

Path & Query

1
  • batch_idstringrequired

    The UUID returned by POST /tts/batch.

Errors

2
404Batch not found

No batch with this ID exists on your account.

Check the batch_id returned by POST /tts/batch.

422Invalid batch_id

batch_id is not a valid UUID.

Pass the exact UUID returned by POST /tts/batch.