curl --request POST \
  --url https://tts.us.assemblyai.com/v1/speech \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "text": "Hello from AssemblyAI."
}
'

"<string>"

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: it is never cut. 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. Word timings are not available on this route; use Stream speech with word timings.

POST

speech

curl --request POST \
  --url https://tts.us.assemblyai.com/v1/speech \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "text": "Hello from AssemblyAI."
}
'

"<string>"

Authorizations

Authorization

string

header

required

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

X-Client-Request-Id

string

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 - 512

Body

application/json

The body of a speech request: one UTF-8 JSON object of at most 131,072 bytes, sent with 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. Body fields are never read from the query string: a field sent there is refused with 422, naming it.

text

string

required

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, and it is read as written, as on the WebSocket API (numbers, currency, markup and emoji reach the model as sent); see How text is read.

Required string length: 1 - 5000

voice_id

string

The 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 AssemblyAI voice the model does not speak in the request's language is refused with 422 invalid_request. Any other voice speaks its own language, and 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; 400 feature_not_enabled where cloned voices are not available on the host; 503 voice_service_unavailable when the voice could not be looked up.

Required string length: 1 - 64

model_id

string

The name of the model to speak with, such as assemblyai-tts-1, in lowercase. Left out, the default model of the language. With voice_id, the voice must be paired 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 - 48

true 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). 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.

language

enum<string>

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.

Available options:

english,

spanish,

german,

italian,

portuguese,

french

sample_rate

enum<integer>

default:24000

The sample rate of the audio in Hz.

Available options:

8000,

16000,

22050,

24000,

44100,

48000

encoding

enum<string>

default:pcm_s16le

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

container

enum<string>

default:raw

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

bit_rate

enum<integer>

default:64000

The MP3 bit rate in bits per second. MP3 only, and at most 64000 at 8 kHz.

Available options:

32000,

48000,

64000,

96000,

128000

stream

boolean

default:true

false returns the whole clip at once, with Content-Length, instead of streaming it.

word_boundaries

boolean

default:false

true is refused on this route: word timings come from Stream speech with word timings.

speed

number

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.

Getting started

Features

Integrations

API reference

Advanced

Create speech

Authorizations

Headers

Body

Response