Skip to main content
WSS
token
type:string
required

Optional. Authenticate with a temporary token (minted with product=tts) or an API key, for clients that cannot set the Authorization header, such as browsers. Ignored when the Authorization header carries a credential; a header that is empty or only Bearer carries none. Mint one temporary token per connection, and never put your API key in a URL that runs on a user's device.

voice_id
type:string
required

Optional. The voice: the library slug of an AssemblyAI voice such as aai-kyla, 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. Slugs are lowercase, at most 64 characters. When unset, the session speaks the default voice of its language, such as aai-kyla in English. An AssemblyAI voice the session's model does not speak in the session's language closes with 3006; a voice_id that names no voice your account can use on this host closes with 3012.

model_id
type:string
required

Optional. The model to run the session on, such as assemblyai-tts-1, in lowercase; latest names the default model of the session's language. When unset, the default model of the session's language in the region. A cloned voice in voice_id must be paired with that model (3014 otherwise). A model the region does not know, or one that does not speak the session's language, closes with 3006 before Begin. See Language and model.

language
type:enum
required

Optional. The language of the text you send, as its full English name, not an ISO code. Case-insensitive, echoed lowercase. The API does not detect language. Defaults to the language of the voice in voice_id, and to english when you name no voice. A value outside this list closes the session with 3006 before Begin, and so does a language the voice cannot speak on the session's model (never on assemblyai-tts-1, which speaks every voice in all six languages, though results are usually worse than in the voice's own language; see Voice and language). See Languages.

Available options: english, spanish, german, italian, portuguese, french
sample_rate
type:enum
required

Optional. Output sample rate in Hz. 24000 is the model's native rate; other rates are resampled.

Available options: 8000, 16000, 22050, 24000, 44100, 48000
encoding
type:enum
required

Optional. Encoding of the audio in Audio messages: raw bytes with no header. pcm_s16le is 16-bit signed little-endian PCM; pcm_mulaw and pcm_alaw are 8-bit G.711 for telephony. The aliases mulaw and alaw are accepted and echoed in canonical form. See Audio formats on WebSocket API basics.

Available options: pcm_s16le, pcm_mulaw, pcm_alaw
word_boundaries
type:enum
required

Optional. Whether to send a WordBoundaries message with per-word timings after each request's FlushDone. Takes true, false, 1 or 0, in any case. See Word boundaries.

Available options: true, false
inactivity_timeout
type:string
required

Optional. Seconds with no frame in either direction before the session closes with 3006 (error_type inactivity_timeout). Shortens the idle timeout every session has. An integer from 5 to 120; Begin.configuration.limits reports the accepted range.

extend_biometric_consent
type:enum
required

Optional. With voice_id, by the owner of a cloned voice only, true renews the voice's biometric consent and attests renewed consent on behalf of the account that owns it. Set on a voice your account does not own, an AssemblyAI voice included, the session closes with 3006 (error_type not_owner), and set without voice_id, with 3006 (error_type invalid_parameter). The account must have accepted the biometric data terms (3006 biometric_terms_not_accepted otherwise). See Renew consent.

Available options: true, false
Generate
type:object

Client message with text to speak.

Flush
type:object

Client message that concludes the current request.

Cancel
type:object

Client message that stops the speech in flight, for barge-in.

Keep Alive
type:object

Client message that restarts the idle timer.

Terminate Session
type:object

Client message that ends the session cleanly.

Session Begins
type:object

Server message confirming the session opened, with its effective configuration.

Audio
type:object

Server message with a chunk of synthesized audio.

Flush Done
type:object

Server message confirming a request's audio has all been sent.

Word Boundaries
type:object

Server message with per-word timings for a request.

Cancelled
type:object

Server message answering a Cancel.

Session Terminated
type:object

Server message with the session summary after a clean Terminate.

Error
type:object

Server message sent before every failure close, with the reason.