HTTP API basics

​

Hosts and data zones

​

Authentication

curl https://tts.us.assemblyai.com/v1/speech \
  -H "Authorization: $ASSEMBLYAI_API_KEY" \
  -d '{"text": "Hello from AssemblyAI."}' \
  -o hello.pcm

• The credential is read from the Authorization header only; send exactly one. Without it the answer is 401 missing_authorization, also when the query string carries a token, which is never read.
• A temporary token, minted with product=tts, works wherever an API key does, in the same header. In a page or an app, use a temporary token rather than an API key. A token stays valid for any number of requests until it expires, so a failed request can be retried with the same token. Mint a new token for each request where you can, and keep expires_in_seconds short. Mint the next token while the current reply plays, so that no request waits for a mint.
• A temporary token’s max_session_duration_seconds caps how long a request with it may run.
• List models (OpenAI compatible) and List models (OpenRouter) take no credential; one that is sent is not checked.
• Every 401 carries WWW-Authenticate: Bearer realm="assemblyai".

​

Calling from a browser

​

Requests and responses

• Body. One UTF-8 JSON object of at most 131,072 bytes, with or without a Content-Length header: a body streamed without one, chunked over HTTP/1.1 or over HTTP/2, is read until it ends. A larger one is refused with 413 request_too_large, a body that does not arrive within 10 seconds with 408 request_timeout, and one that is not a JSON object, or that nests about 10,000 levels deep or more, with 400 invalid_message. The Authorization header is checked before the body is read, so a request without a credential is refused without waiting for its body. Content-Type is not checked, so curl -d works as is.
• Fields. null counts as leaving a field out. Types are strict: "sample_rate": 24000.0 and "sample_rate": "24000" are refused. Strings other than the text are trimmed. A field given twice is refused with 422 invalid_parameter: <field>: must be given at most once (given 2 times). Fields are read from the body only: one sent in the query string is refused with 422 (400 on the OpenAI-compatible route), naming it, and other query parameters are ignored.
• Voices are named with voice_id on /v1/speech and /v1/speech/events: an AssemblyAI voice by its library slug, such as aai-jane, any voice by its ID, or one of your cloned voices by its ID or slug. voice is retired on these two routes: a body or a query string that carries it, in any letter case, is refused with 422 invalid_parameter on voice; for a built-in voice, the message names the voice_id to send instead, such as voice_id=aai-jane for jane. The OpenAI-compatible route keeps OpenAI’s voice field; see Create speech (OpenAI compatible).
• Unknown fields are ignored and listed in the X-TTS-Unknown-Params header (sorted, comma-separated, at most 16), so a misspelt field shows up instead of being dropped silently.
• Paths are exact: a trailing slash, such as /v1/speech/, answers 404 not_found, with no redirect. A method a path does not serve answers 405 method_not_allowed, with an Allow header listing the methods it serves: OPTIONS, POST on the speech routes, GET, HEAD, OPTIONS on the others. Accept is not read.
• Request ids. Every response carries X-Request-Id, errors and the answer to a browser’s CORS preflight included; quote it in support requests. Send your own id in X-Client-Request-Id (1 to 512 printable ASCII characters) to have it echoed back and kept with the request’s records. An invalid one is dropped on /v1/speech and /v1/speech/events, and refused with 400 invalid_parameter on the OpenAI-compatible route.
• Responses may gain headers, fields and event types over time. Read the ones you need and ignore the rest.

​

The status waits for the first audio

​

Response headers

​

Audio formats

curl -sS --fail-with-body https://tts.us.assemblyai.com/v1/speech \
  -H "Authorization: $ASSEMBLYAI_API_KEY" \
  -d '{"text": "Your appointment is confirmed.", "encoding": "pcm_mulaw", "sample_rate": 8000}' \
  -o confirm.ulaw

• Whole samples per write, not per read. The server writes whole samples, about 80 ms of audio at a time, but the network can split a write. Carry an odd byte of 16-bit audio over to the next read, as a client that decodes samples must.
• WAV. A streamed WAV file does not know its length when its header is sent, so the header’s two size fields hold 0xFFFFFFFF, which players and decoders read as “until the end of the file”. Some tools read the placeholder fact sample count of a streamed G.711 file as its length and report a duration of days; ffprobe does, so fix the sizes as below before handing such a file to them. The header is 44 bytes for pcm_s16le (format 1) and 58 bytes for pcm_mulaw (format 7) and pcm_alaw (format 6), which add a fact chunk; parse the chunks rather than assuming 44 bytes. To store a streamed WAV file with exact sizes, set bytes 4 to 7 to the file size minus 8 and the data size (bytes 40 to 43, or 54 to 57 for G.711, and the fact sample count at 46 to 49) to the file size minus the header size. A buffered WAV file carries its exact sizes.
• MP3 is constant bit rate, mono, with no ID3 tag, and every frame decodes on its own. Its encoder puts about 1,100 samples of silence before the speech: 46 ms at 24 kHz, 138 ms at 8 kHz. A buffered MP3 file starts with an Xing frame that tells players to skip it; a streamed one cannot, so each streamed MP3 response starts with that silence. For a voice agent, ask for pcm_s16le: it starts sooner and decodes for free.

​

Errors

{
  "code": "invalid_parameter",
  "message": "sample_rate: sample_rate 12345 not in supported set [8000, 16000, 22050, 24000, 44100, 48000]",
  "param": "sample_rate",
  "request_id": "2f0c1d9e-7b4a-4c3e-9a51-6d8e2b7f4c10",
  "errors": [
    {
      "message": "sample_rate 12345 not in supported set [8000, 16000, 22050, 24000, 44100, 48000]",
      "param": "sample_rate"
    }
  ],
  "retryable": false,
  "retry_after_seconds": null,
  "error": "sample_rate: sample_rate 12345 not in supported set [8000, 16000, 22050, 24000, 44100, 48000]"
}

{
  "error": {
    "message": "model: 'tts-1' is not an AssemblyAI model; use one of GET /v1/openai/models, such as assemblyai-tts-en",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found",
    "request_id": "93309b7e-9131-474f-99e4-6e0623463374",
    "retryable": false,
    "retry_after_seconds": null
  }
}

​

Error codes

​

Answers without the JSON body

​

Limits

• It is ten times the account’s WebSocket session limit: unless your account has a limit of its own, 50 requests a minute on a free plan and 1,000 or more on a paid plan. On a paid plan it scales with use as the session limit does: a minute that uses 80% or more of it raises the next by 10%. A voice agent that sends one request per sentence sends about 15 to 20 a minute per conversation.
• It counts requests in fixed one-minute windows; Retry-After is the time until the next window starts. Requests refused before the limit is checked, such as one with a bad field, do not count; a request refused after it, such as one for a voice the model does not speak, does.
• Characters are not counted on their own: a request carries at most 5,000.
• The limit in a 429 body and in its message is your starting limit; on a paid plan the limit in force can be higher.
• The US and EU hosts count separately.

​

Keep latency low

• Stream, and play the first bytes. Leave stream at its default and read the body as it arrives. A streamed response sends its first byte with the first audio, while a buffered request ("stream": false) sends its first byte only when the whole clip is ready, so its wait grows with the length of the text.
• Send each sentence as soon as you have it. The time to the first audio of a streamed request does not grow with the length of the text. A voice agent that sends the first sentence of a reply as its own request as soon as the LLM has written it starts speaking sooner than one that waits for the whole reply. For text that arrives a few words at a time, the WebSocket API takes it as it is written and starts speaking as soon as it holds enough of the first sentence.
• Ask for raw audio in the format your player needs. pcm_s16le at your player’s sample rate, or 8 kHz pcm_mulaw or pcm_alaw for a phone line, is ready to play as it arrives; converting to a sample rate other than 24 kHz adds a few milliseconds at most. A streamed MP3 response starts with the encoder’s silence, about 46 ms at 24 kHz and 138 ms at 8 kHz, and needs a decoder; see Audio formats.
• Keep the connection open between replies. Reuse one client, as above, and open its connection before the first reply, for example when a call starts, with any cheap request: HEAD /v1/openai/models takes no credential and synthesizes nothing. Each new connection costs the TCP and TLS handshakes, about two network round trips.
• Use the data zone nearest to the machine that calls the API, and, when your agent also transcribes speech with AssemblyAI, the same zone for both; a cloned voice is usable only in the zone it was created in. See Hosts and data zones.
• Have a temporary token ready. A page or an app that fetches a token from your server before each request adds that round trip and the mint to every reply; fetch the next one while the current reply plays.
• Expect the first request with a voice to start a little later. A voice that has not spoken recently, a cloned voice especially, takes longer to start on its first request than on the requests after it.

​

Billing

​

Related

• OpenAI compatibility: OpenAI SDKs, LiveKit and Pipecat.
• Error handling: the same conditions on the WebSocket API.