Skip to navigation

Stream speech (real-time TTS)

Streaming variant of /v1/audio/speech. Returns Server-Sent Events as the model synthesizes, with sub-130ms time-to-first-byte on Inworld TTS Mini, sub-250ms on Max. Use this for voice agents and other interactive playback paths.

Event types:

  • audio.chunk: base64-encoded audio bytes with seq, format, sample_rate, and elapsed_ms fields. Concatenate client-side for progressive playback.
  • audio.timestamps: emitted when timestamp_type is WORD or CHARACTER, carrying per-token timing info.
  • audio.done: final event with the complete file’s hosted url and its format, the total duration, and usage, plus voice_id and voice_id_expires_at when the request created a custom voice.
  • audio.warning: a notice with a message that does not end the stream, for example when the hosted copy of the audio could not be created; audio.done then has an empty url.
  • audio.error: a failure after the stream started, with its type, seq, and error; followed by [DONE].
  • [DONE]: terminator (standard SSE).

A failure before the first event returns an ordinary error response with the HTTP status of that failure, such as 400, 404, or 429, instead of a stream.

Models that stream list POST /v1/audio/speech:stream in supported_endpoints on GET /v1/models/{id}; other TTS models use the synchronous /v1/audio/speech endpoint. Billing matches /v1/audio/speech for the same model, and a stream the client cancels is billed for the synthesis the model completed.

On Gemini 3.8 Flash TTS and Flash-Lite TTS, every audio.chunk carries 16-bit PCM at 24 kHz, and audio.done links the complete file in the requested output_format and sample_rate. speed is available on /v1/audio/speech only.

Authentication

AuthorizationBearer

Pass your EmpirioLabs API key as a bearer token. The Anthropic-style x-api-key header is also accepted on every endpoint.

Request

This endpoint expects an object.
modelstringRequired
inputstringRequired
Text to synthesize. Max 3000 characters per request.
voicestringOptional
voice_idstringOptional

Free-form voice ID; use to address the full 271-voice catalog.

languagestringOptional
output_formatenumOptionalDefaults to WAV
Allowed values:
sample_rateenumOptionalDefaults to 24000
speeddoubleOptionalDefaults to 1
temperaturedoubleOptionalDefaults to 1
timestamp_typeenumOptionalDefaults to NONE
Allowed values:

Response

Server-Sent Events stream (text/event-stream).

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
429
Too Many Requests Error