Stream Speech With Timestamps

Synthesize speech and stream it back together with word-level speech marks, for text highlighting, captions and audio-text synchronization while the audio is still arriving.

The response is a Server-Sent Events stream. Each speech.chunk event carries a Base64-encoded run of audio, the speech marks that became final with it, or both - a chunk may carry only one of the two, and the last chunk of a stream is often marks-only. A terminal speech.done event ends the stream; there is no [DONE] sentinel. Ignore any event type you do not recognize, so that new event types do not break your integration.

Speech-mark times are absolute milliseconds from the start of the synthesis, so concatenate the audio chunks into one stream and apply the marks against that single timeline. Which chunk a mark arrives on is a delivery detail and carries no meaning. Times stay correct for every output_format: changing the codec or sample rate does not change the duration.

Speech marks are produced by the streaming-native models. The default simba-3.0 and simba-3.2 both serve this route. The legacy simba-english and simba-multilingual models never could: on a workspace pinned before API version 2026-09-21 they return 400 speech_marks_unsupported here, and from that version on they return 400 model_retired on every synthesis route. Both are switched off entirely on 2026-11-21. For Base64-encoded audio and speech marks in one non-streamed JSON response, on any model, use POST /v1/audio/speech.

Synthesize speech and stream it back together with word-level speech marks, for text highlighting, captions and audio-text synchronization while the audio is still arriving. The response is a Server-Sent Events stream. Each `speech.chunk` event carries a Base64-encoded run of audio, the speech marks that became final with it, or both - a chunk may carry only one of the two, and the last chunk of a stream is often marks-only. A terminal `speech.done` event ends the stream; there is no `[DONE]` sentinel. Ignore any event type you do not recognize, so that new event types do not break your integration. Speech-mark times are absolute milliseconds from the start of the synthesis, so concatenate the audio chunks into one stream and apply the marks against that single timeline. Which chunk a mark arrives on is a delivery detail and carries no meaning. Times stay correct for every `output_format`: changing the codec or sample rate does not change the duration. Speech marks are produced by the streaming-native models. The default `simba-3.0` and `simba-3.2` both serve this route. The legacy `simba-english` and `simba-multilingual` models never could: on a workspace pinned before API version `2026-09-21` they return 400 `speech_marks_unsupported` here, and from that version on they return 400 `model_retired` on every synthesis route. Both are switched off entirely on 2026-11-21. For Base64-encoded audio and speech marks in one non-streamed JSON response, on any model, use POST /v1/audio/speech.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Request

This endpoint expects an object.

inputstringRequired<=20000 characters

Plain text or SSML to be synthesized to speech. Refer to https://docs.speechify.ai/docs/api-limits for the input size limits. Emotion, Pitch and Speed Rate are configured in the ssml input, please refer to the ssml documentation for more information: https://docs.speechify.ai/docs/ssml#prosody

voice_idstringRequired

Id of the voice to be used for synthesizing speech. Refer to /v1/voices endpoint for available voices

languagestringOptional

Language of the input. Follow the format of an ISO 639-1 language code and an ISO 3166-1 region code, separated by a hyphen, e.g. en-US. Please refer to the list of the supported languages and recommendations regarding this parameter: https://docs.speechify.ai/docs/language-support.

modelenumOptionalDefaults to simba-3.0

Model used for audio synthesis. Defaults to simba-3.0, which is streaming-native and multilingual: it officially supports English plus de-DE, es-ES, es-MX, fr-FR, it-IT and pt-BR, and routes each request to its English or its multilingual training based on language (falling back to the voice’s locale when language is omitted). simba-3.2 is the streaming-native model with the lowest TTFB and richest expressivity, and the recommended Simba 3 model; it is English only, so a non-English voice returns 400.

The legacy Simba 1.6 models simba-english and simba-multilingual are retired from API version 2026-09-21: naming one returns 400 model_retired. Pinning your API version to a date before 2026-09-21 keeps them working until 2026-11-21, when both are switched off for every API version. Migrate to simba-3.2 (English) or simba-3.0 before then; call GET /v1/audio/models to see the set your workspace can select today.

optionsobjectOptional

GetStreamOptionsRequest is the wrapper for request parameters to the client

output_formatenumOptional

The output audio format as a codec_sampleRate_bitrate string. Takes precedence over the Accept header when set, so you can request formats the Accept enum does not cover (e.g. pcm_16000, ulaw_8000). wav_* formats are not supported on streaming - use POST /v1/audio/speech for wav.

Response headers

Speechify-Request-IdstringOptional

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a Speechify-Request-Id request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests

it is the stable handle that ties your observation to Speechify’s server-side logs, and it matches the request_id field in the error envelope.

The legacy alias X-Request-ID carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a `Speechify-Request-Id` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope. The legacy alias `X-Request-ID` carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

RateLimit-Limitinteger

Request-rate budget: the maximum number of requests in the current window (the bucket capacity). The IETF-draft un-prefixed name; the legacy alias X-RateLimit-Limit carries the same value. Rides every response.

RateLimit-Remaininginteger

Request-rate budget: requests left in the current window. Legacy alias: X-RateLimit-Remaining.

RateLimit-Resetinteger

Request-rate budget: integer delta-seconds until the window fully refills (same unit as Retry-After). Legacy alias: X-RateLimit-Reset.

Speechify-Audio-Content-TypestringOptional

Media type of the audio carried inside the events (for example audio/mpeg), which the response’s own text/event-stream Content-Type cannot express.

Response

A Server-Sent Events stream of speech.chunk events followed by one terminal speech.done event. A failure after the stream has started is delivered as a speech.error event carrying the standard error envelope, because the status code is already committed.

The transport is text/event-stream: each event is an event:/data: pair whose data is one JSON payload matching the schema below. The payload’s type field mirrors the event: name, so the stream is also parseable from data: lines alone. Ignore event types you do not recognize.

A Server-Sent Events stream of `speech.chunk` events followed by one terminal `speech.done` event. A failure after the stream has started is delivered as a `speech.error` event carrying the standard error envelope, because the status code is already committed. The transport is `text/event-stream`: each event is an `event:`/`data:` pair whose `data` is one JSON payload matching the schema below. The payload's `type` field mirrors the `event:` name, so the stream is also parseable from `data:` lines alone. Ignore event types you do not recognize.

speech.chunkobject

A run of synthesized audio, the speech marks that became final with it, or both - a chunk may carry only one of the two, and the last chunk of a stream is often marks-only. Mark times are absolute milliseconds from the start of the synthesis: concatenate the audio chunks into one stream and apply the marks against that single timeline. Which chunk a mark arrives on is a delivery detail and carries no meaning.

speech.doneobject

Terminal event: the synthesis completed and no further events follow. There is no [DONE] sentinel.

speech.errorobject

Terminal event carrying the standard error envelope, emitted when a failure happens after the stream has started and the status code is already committed.

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

429

Too Many Requests Error

500

Internal Server Error

502

Bad Gateway Error

503

Service Unavailable Error

1	from speechify import Speechify
2
3	client = Speechify(
4	token="YOUR_TOKEN_HERE",
5	)
6
7	client.audio.stream_with_timestamps(
8	input="Streaming long-form audio with the Speechify API.",
9	model="simba-3.2",
10	voice_id="geffen_32",
11	)