Skip to main content
POST

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, echoed in the response. An invalid value is refused with 400, code invalid_parameter.

Required string length: 1 - 512

Body

application/json

The OpenAI speech request. Fields this route does not use are ignored and listed in X-TTS-Unknown-Params.

model
string
required

A language's model name, such as assemblyai-tts-en (the language follows the code), or a model's name such as assemblyai-tts-1, optionally prefixed assemblyai/. Case-insensitive. A name that is not an AssemblyAI model name, OpenAI's model names such as tts-1 included, is refused with model_not_found, and so is a model name the region does not serve.

input
string
required

The text to speak, 1 to 5,000 Unicode code points, not blank. An array is refused.

Required string length: 1 - 5000
voice

The library slug of an AssemblyAI voice, such as aai-kyla, a voice's UUID, or an OpenAI voice name such as alloy, ash, ballad, cedar, coral, echo, fable, marin, nova, onyx, sage, shimmer or verse. Every OpenAI voice name speaks with the default voice of the request's language, such as aai-kyla in English. OpenAI voice names are case-insensitive; a slug is lowercase. A bare AssemblyAI voice name such as kyla is refused with 422 (invalid_parameter) and param voice. Other values are not supported: a misspelt name, a file name, a path or a URL is refused with 422 like a bare name, and a slug or UUID that names no voice with 400 (invalid_request). Left out, the default voice of the language, such as aai-kyla in English. A cloned voice goes in as {"id": "<voice ID or slug>"}, or as a string holding its UUID; the slug of one of your voices in a plain string is refused.

response_format
enum<string>
default:mp3

mp3 (24 kHz, 64 kbps), pcm (raw 16-bit little-endian), wav (16-bit PCM in a WAV file), mulaw or alaw (raw G.711), case-insensitive. The sample rate is 24 kHz unless sample_rate says otherwise. opus, aac and flac are refused.

Available options:
mp3,
pcm,
wav,
mulaw,
alaw
stream_format
enum<string>
default:audio

audio streams the audio bytes; sse streams speech events. Case-insensitive.

Available options:
audio,
sse
speed
number

Accepted when it equals 1; any other value is refused.

language
string

Extension: the language to speak, as a name (english) or an ISO 639-1 code (en). Refused when it differs from the language model implies.

sample_rate
enum<integer>
default:24000

Extension: the sample rate of the audio in Hz.

Available options:
8000,
16000,
22050,
24000,
44100,
48000
voice_id
string

Extension: the ID or slug of a voice, such as a cloned voice, for clients that cannot send voice as an object. Leave voice out. Next to a voice, it must repeat the same ID or slug (a UUID in any letter case): next to an OpenAI voice name such as alloy, or next to the same voice under its other identifier, such as its ID in voice and its slug in voice_id, it is refused with invalid_parameter.

Required string length: 1 - 64

Extension: true renews the biometric consent of a cloned voice, and attests renewed consent on behalf of the account that owns the voice; see Renew consent. Only the voice's owner may set it. The voice must be named as {"id": ...} in voice, as its UUID in the voice string, or in voice_id: with no voice it is refused with invalid_parameter (extend_biometric_consent: needs the voice by its id: {"id": ...} or a voice id in voice), and on another account's voice, an AssemblyAI voice such as aai-kyla in any form included, or with an OpenAI voice name such as alloy in an English request, with not_owner. In another language, an OpenAI voice name is refused with invalid_parameter. The slug of one of your own voices in the voice string is refused with 422 invalid_parameter on voice; send it as {"id": ...}. The account must have accepted the biometric data terms (403 biometric_terms_not_accepted). The renewal is not guaranteed: one that cannot be made leaves the expiry as it was.

word_boundaries
boolean
default:false

Must be false or left out; word timings come from POST /v1/speech/events.

Response

The audio, or speech events with stream_format sse.

Raw audio in the requested format. Streamed responses are chunked and end cleanly only when the audio is complete.