HTTP API
Create speech
Synthesize text and return the audio as the response body.
Streamed (default). The status line and the headers are sent together with the first audio, once synthesis has produced it. Every failure before that point is an ordinary HTTP error with a JSON body, so a 200 carries audio unless the text has nothing to speak. The body is chunked, with no Content-Length, and holds raw audio in the requested format: bytes arrive as they are synthesized, faster than real time. A body that ends cleanly holds the complete audio. If the request fails after the audio started, the connection is cut before the end of the body, so the client reports an error (curl exits with code 18 or 92, Python requests raises ChunkedEncodingError, httpx raises RemoteProtocolError, fetch rejects the read with a TypeError); a cut caused by a server failure is not billed.
Buffered ("stream": false). Nothing is sent until the whole clip is ready. The answer is either a 200 with the complete audio, Content-Length and X-TTS-Audio-Duration-Ms, or an error status. A failure on our side never cuts it; a client that stops reading it for 30 seconds has the connection closed before the end of the body. A WAV body carries its exact sizes, and an MP3 body starts with an Xing frame so that players skip the encoder delay. The first byte arrives about when the last one would have arrived streamed.
Formats. encoding and container pick the format: raw 16-bit PCM (default), raw G.711 mu-law or A-law, the same in a WAV file, or MP3. The Content-Type names the format, with the sample rate for raw audio: audio/pcm;rate=24000;channels=1, audio/PCMU;rate=8000;channels=1, audio/PCMA;rate=8000;channels=1, audio/wav or audio/mpeg. A streamed WAV header has the size fields 0xFFFFFFFF (unknown; read to the end): 44 bytes for pcm_s16le, 58 bytes for pcm_mulaw and pcm_alaw (format 7 or 6 with a fact chunk). Parse the chunks rather than assuming 44 bytes. MP3 is constant bit rate, mono, with no ID3 tag. Each write holds whole samples or whole MP3 frames, but the network can split them, so carry an odd byte over to the next read.
Text with nothing to speak, such as text made only of emoji, answers 200 with no audio: Content-Length: 0 for raw and MP3, a WAV header with real sizes for WAV, and X-TTS-Billed-Characters: 0. It is not billed.
Unknown body fields are ignored and listed in X-TTS-Unknown-Params. Name the voice with voice_id: voice is retired, and a body or a query string that carries it is refused with 422 invalid_parameter on voice; for a built-in voice, such as jane, the message names the voice_id to send instead. Word timings are not available on this route; use Stream speech with word timings.
POST
Authorizations
Your AssemblyAI API key, or a temporary token, in the Authorization header. The raw key works directly; a Bearer prefix is also accepted, which is what OpenAI SDKs send. Send exactly one Authorization header. The HTTP routes read the credential from this header only.
Headers
Your own id for the request, 1 to 512 printable ASCII characters. It is echoed in the response and kept with the request's records. It need not be unique; X-Request-Id is the unique key. An invalid value is ignored and not echoed.
Required string length:
1 - 512Body
application/json
The body of a speech request: one UTF-8 JSON object of at most 131,072 bytes, with or without a Content-Length header. Content-Type is not checked. null counts as leaving a field out. Types are strict: "sample_rate": 24000.0 and "sample_rate": "24000" are refused. Strings other than text are trimmed. A field given twice is refused. Unknown fields are ignored and listed in X-TTS-Unknown-Params, except voice, which is retired: a body that carries it, in any letter case, is refused with 422 invalid_parameter on voice, and for a built-in voice, such as jane, the message names the voice_id to send instead. Body fields are never read from the query string: a field sent there is refused with 422, naming it.
The text to speak, 1 to 5,000 Unicode code points. It may not be blank or hold U+0000 or an unpaired surrogate. It is not trimmed. It is read as on the WebSocket API, so the server writes out common forms such as amounts, phone numbers and dates with a year in words, and drops markup and emoji, before the model reads it; see How text is read.
Required string length:
1 - 5000The voice. The library slug of an AssemblyAI voice, such as aai-jane; a voice's ID, a UUID in any letter case; or the slug of one of your account's voices, such as a cloned voice. A slug is lowercase. Left out, the default voice of the model and language, aai-jane, an English voice. An AssemblyAI voice the model does not speak in the request's language is refused with 422 invalid_request. A cloned voice speaks its own language unless language names another one. In another language, results are usually worse than in the voice's own language, for aai-jane as for any voice (Voice and language). A voice the request cannot use is refused before any audio, with 422 and the code voice_not_found, voice_expired, voice_blocked, voice_not_paired, model_retired or model_not_found, or invalid_parameter on language for a language the voice does not speak; 503 voice_service_unavailable when the voice could not be looked up. One of your own voices also needs the biometric data terms, with 403 biometric_terms_not_accepted when your account has not accepted them and 503 auth_unavailable when they could not be checked.
Required string length:
1 - 64The name of the model to speak with, such as assemblyai-tts-1, in lowercase. Left out, the default model of the language. With a cloned voice in voice_id, the voice must be ready to speak with it (422 voice_not_paired otherwise). A model the region does not know is refused with 422 model_not_found.
Required string length:
1 - 48true renews the biometric consent of the cloned voice in voice_id, and attests renewed consent on behalf of the account that owns the voice; see Renew consent. Only the voice's owner may set it: on another account's voice it is refused with 422 not_owner, and without voice_id with 422 invalid_parameter (extend_biometric_consent: extend_biometric_consent requires voice_id). The account must have accepted the biometric data terms (403 biometric_terms_not_accepted otherwise). When the request passes its voice checks and renewals are available to your account, the server renews the consent in the background: the voice's expiry moves to 60 days after the request started, if that moves it later by at least one day. The renewal is not guaranteed: one that cannot be made leaves the expiry as it was.
The language to speak, as its full name, case-insensitive. Left out, English, or with voice_id the voice's own language. A supported language no model of the region speaks is refused with 422 invalid_request, and a value outside the supported set with 422 invalid_parameter; see Languages. With voice_id, a language the voice does not speak on the model is refused with 422 invalid_parameter; assemblyai-tts-1 speaks every voice in all six languages, though results are usually worse than in the voice's own language. See Voice and language.
Available options:
english, spanish, german, italian, portuguese, french The sample rate of the audio in Hz.
Available options:
8000, 16000, 22050, 24000, 44100, 48000 The audio encoding, case-insensitive. mulaw and alaw are aliases, reported in canonical form. opus, aac and flac are refused.
Available options:
pcm_s16le, pcm_mulaw, pcm_alaw, mulaw, alaw, mp3 raw sends the encoded samples alone; wav puts them in a WAV file. wav needs a pcm_* encoding, and MP3 has no container. Case-insensitive.
Available options:
raw, wav The MP3 bit rate in bits per second. MP3 only, and at most 64000 at 8 kHz.
Available options:
32000, 48000, 64000, 96000, 128000 false returns the whole clip at once, with Content-Length, instead of streaming it.
true is refused on this route: word timings come from Stream speech with word timings.
Accepted when it equals 1; any other value is refused.
Response
The audio. Streamed unless the request set "stream": false.
Raw audio in the requested format. Streamed responses are chunked and end cleanly only when the audio is complete.