Skip to main content
POST
Stream With Timestamps
This endpoint returns text/event-stream. Each SSE message event contains one JSON payload with a base64-encoded audio chunk.
Use this endpoint when you need both progressive audio delivery and text-to-audio alignment data, such as karaoke-style highlighting, word or phrase progress indicators, captions synchronized to generated speech, or timeline editing.

​
How the Stream Works

The response is a Server-Sent Events stream. Every event includes: audio_base64 is the transport stream. alignment is a metadata snapshot for chunk_seq. They are delivered together in the same SSE event, but the alignment is not a per-audio-packet delta. When latency is set to balanced, long input can be split into several text chunks. A chunk may produce multiple non-null alignment snapshots as more audio is rendered. Each newer snapshot supersedes the previous snapshot for the same chunk_seq.
Store alignments in a map keyed by chunk_seq. On every non-null alignment, replace the stored value for that key. Do not collect every non-null alignment as a separate final result.

​
Alignment Shape

Each non-null alignment contains the current cumulative timing segments for a single text chunk:
start and end are measured in seconds from the start of that text chunk’s generated audio. Add chunk_audio_offset_sec to get timestamps on the complete audio timeline. alignment can be null before the first snapshot is available or when alignment is unavailable. After a snapshot exists, later audio events may repeat the latest snapshot so clients can continue using a simple latest-wins update model.

​
Minimal Request

​
Parsing the Stream

The stream payload uses standard SSE framing. Parse each data: line as JSON, append every decoded audio_base64 chunk to your audio buffer, and replace the latest alignment snapshot for chunk_seq whenever alignment is non-null.

​
Handling Split Content Chunks

Long input can produce multiple text chunks. Treat audio and alignment as two related streams:
  1. Append every decoded audio_base64 chunk in event order. Do this even when alignment is null.
  2. For non-null alignment, replace the stored snapshot for chunk_seq.
  3. Convert each snapshot’s local segment times into global times by adding chunk_audio_offset_sec.
audio_base64 chunks are transport chunks, not sentence or word boundaries. Do not try to align each audio chunk individually. Use alignment.segments plus chunk_audio_offset_sec for text timing.
For example, if an event has chunk_audio_offset_sec: 16.24, add 16.24 seconds to every segment in that event’s alignment before rendering it on the complete audio timeline.

​
Format Guidance

For timestamped streaming, we recommend opus with the default 48 kHz sample rate when your client supports it. Opus is designed for streaming and gives the best balance of quality, latency, and bandwidth for this endpoint. wav and pcm avoid lossy codec artifacts and are straightforward to align, but they produce much larger payloads. Use them when you need uncompressed audio, direct sample-level processing, or a playback pipeline that already expects raw audio.
Use mp3 only when broad playback compatibility is more important than the cleanest streaming boundaries. MP3 encoding uses overlapping audio windows, so its encoded chunks may not line up as neatly with timestamp snapshot updates as Opus.
This endpoint accepts the same TTS request fields as the Text to Speech API, including reference_id, references, prosody, temperature, top_p, chunk_length, format, and latency.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
model
enum<string>
default:s2.1-pro

Specify which TTS model to use. Use s2.1-pro-free for the free developer tier. If omitted or set to an unrecognized value, the request falls back to s2.1-pro.

Available options:
s1,
s2-pro,
s2.1-pro,
s2.1-pro-free,
drama-3

Body

Request body for streaming text-to-speech synthesis with timestamp alignment. The request fields match the standard TTS endpoint, but the response is delivered as a Server-Sent Events stream. Each SSE payload includes an audio chunk and, when available, the latest cumulative alignment snapshot for a chunk_seq. Clients should concatenate audio_base64 chunks in arrival order and replace the stored alignment for each chunk_seq whenever a newer snapshot is received.

​
text
string
required

Text to convert to speech.

​
temperature
number
default:0.7

Controls expressiveness. Higher is more varied, lower is more consistent.

Required range: 0 <= x <= 1
​
top_p
number
default:0.7

Controls diversity via nucleus sampling.

Required range: 0 <= x <= 1
​
references

Single speaker: array of reference audio samples

​
reference_id

Single speaker: voice model ID string

​
prosody
ProsodyControl · object | null

Speed and volume adjustments for the output.

​
chunk_length
integer
default:300

Text segment size for processing.

Required range: 100 <= x <= 300
​
normalize
boolean
default:true

Rewrites numbers, dates, units and symbols as spoken words before synthesis, improving stability. Uses language when it is set and otherwise detects the language of each text chunk.

​
language
string | null

BCP-47 language tag of the text, for example en, es-MX or zh-CN. Case-insensitive, and _ is read as -. Used only by text normalization (how numbers, dates, units and symbols are spelled out before synthesis) and by word-timestamp alignment. It is not passed to the speech model and does not change the voice, accent or audio quality; a wrong tag only changes how those tokens are spelled out. Omit it, or send auto or an empty string, to detect the language per chunk. A tag without dedicated normalization rules skips normalization instead of failing. Without a region, Spanish follows Spain conventions; send es-MX for Mexican readings. When normalize is false it only affects word timestamps. For text that mixes languages, leave it unset.

Maximum string length: 35
Pattern: ^[A-Za-z0-9_-]*$
Example:

"en"

​
format
enum<string>
default:mp3

Output audio format.

Available options:
wav,
pcm,
mp3,
opus
​
sample_rate
integer | null

Audio sample rate in Hz. When null, uses the format's default (44100 Hz for most formats, 48000 Hz for opus).

​
mp3_bitrate
enum<integer>
default:128

MP3 bitrate in kbps. Only applies when format is mp3.

Available options:
64,
128,
192
​
opus_bitrate
enum<integer>
default:-1000

Opus bitrate in bps. -1000 for automatic. Only applies when format is opus.

Available options:
-1000,
24000,
32000,
48000,
64000
​
latency
enum<string>
default:normal

Latency-quality trade-off. normal: best quality, balanced: reduced latency, low: lowest latency.

Available options:
low,
normal,
balanced
​
max_new_tokens
integer
default:1024

Maximum audio tokens to generate per text chunk.

​
repetition_penalty
number
default:1.2

Penalty for repeating audio patterns. Values above 1.0 reduce repetition.

​
min_chunk_length
integer
default:50

Minimum characters before splitting into a new chunk.

Required range: 0 <= x <= 100
​
condition_on_previous_chunks
boolean
default:true

Use previous audio as context for voice consistency.

​
early_stop_threshold
number
default:1

Early stopping threshold for batch processing.

Required range: 0 <= x <= 1
​
features
string[]

Optional request-scoped TTS feature flags forwarded verbatim to the inference backend. Use ["quality-guard"] to enable the quality guard for this synthesis request. Feature availability is determined by the inference backend.

​
pronunciation_dictionary
PronunciationDictionaryRef · object

Reference to a server-managed pronunciation dictionary. The server resolves contents via the platform pronunciation-dictionaries API and forwards the full merged dictionary to the inference engine, which performs the substitution.

Response

Server-Sent Events stream. Each message event contains a JSON payload with one base64 audio chunk. Concatenate every audio_base64 chunk in arrival order to reconstruct the complete audio. alignment is the latest cumulative timestamp snapshot for chunk_seq; clients should replace the previous snapshot for that chunk instead of appending segments. chunk_audio_offset_sec can be added to segment times to derive absolute timestamps in the full audio.

One Server-Sent Events message payload for streaming TTS with timestamps. Each event contains one audio chunk. Concatenate all audio_base64 chunks in arrival order to reconstruct the complete audio. alignment is the latest cumulative timestamp snapshot for the reported chunk_seq; clients should replace the previous snapshot for that chunk instead of appending segments.

​
audio_base64
string
required

Base64 encoded audio chunk. Concatenate every chunk in event order to reconstruct the full audio.

​
content
string
required

Text content described by this event's latest alignment snapshot. Long input may be split into multiple content chunks in one stream.

​
alignment
TTSTimestampAlignment · object | null
required

Latest cumulative timestamp snapshot for chunk_seq. When present, replace the previous alignment for the same chunk_seq; do not append segments. Null means no alignment snapshot has been produced yet or alignment is unavailable.

​
chunk_seq
integer
required

Sequence number of the text chunk described by alignment. Clients should bucket alignment snapshots by this value.

Required range: x >= 0
​
chunk_audio_offset_sec
number
required

Absolute start time of this text chunk within the full audio, in seconds.

Required range: x >= 0