---
title: "Text to Speech Stream with Timestamps"
method: POST
path: "/v1/tts/stream/with-timestamp"
tags: ["OpenAPI v1"]
---

# Text to Speech Stream with Timestamps

`POST /v1/tts/stream/with-timestamp`

## Request

- Base URL: `https://api.fish.audio`
- URL: `https://api.fish.audio/v1/tts/stream/with-timestamp`
- Auth: HTTP bearer

## Headers

- `model` 's1' | 's2-pro' | 's2.1-pro' | 's2.1-pro-free' | 'drama-3'

## Request body

- TTSStreamWithTimestampRequest: 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: Controls expressiveness. Higher is more varied, lower is more consistent.
  - `top_p` number: Controls diversity via nucleus sampling.
  - `references` union: Inline voice references for zero-shot cloning. Requires MessagePack (not JSON). For single speaker, provide an array of ReferenceAudio objects. For multiple speakers, provide an array of arrays where each inner array contains references for one speaker. **Multi-speaker is available with the S2 family (`s2-pro`, `s2.1-pro`, `s2.1-pro-free`) and `drama-3`, not `s1`.** The speaker index corresponds to the index in reference_id array. Example for multi-speaker: [[{audio, text}], [{audio, text}, {audio, text}]] for 2 speakers where speaker 1 has 2 reference samples.
    - ReferenceAudio[]: Single speaker: array of reference audio samples
      - `audio` string, binary, required: Raw audio bytes of the voice sample. Supported formats: WAV, MP3, FLAC. For best results, use 10-30 seconds of clear speech with minimal background noise.
      - `text` string, required: The exact transcript of what is spoken in the audio sample. Accuracy is important for voice cloning quality.
    - array[]: Multiple speakers: array of arrays, where each inner array contains reference samples for one speaker
      - ReferenceAudio[]
        - `audio` string, binary, required: Raw audio bytes of the voice sample. Supported formats: WAV, MP3, FLAC. For best results, use 10-30 seconds of clear speech with minimal background noise.
        - `text` string, required: The exact transcript of what is spoken in the audio sample. Accuracy is important for voice cloning quality.
  - `reference_id` union: Voice model ID(s) from Fish Audio library or your custom models. For single-speaker synthesis, provide a string. For multi-speaker synthesis (dialogue), provide an array of model IDs. **Multi-speaker is available with the S2 family (`s2-pro`, `s2.1-pro`, `s2.1-pro-free`) and `drama-3`, not `s1`.** When using multiple speakers, use speaker tags in your text like `<|speaker:0|>` and `<|speaker:1|>` to indicate speaker changes. Example: `<|speaker:0|>Hello!<|speaker:1|>Hi there!<|speaker:0|>How are you?` with `reference_id: ["speaker-a-id", "speaker-b-id"]`.
    - string: Single speaker: voice model ID string
    - string[]: Multiple speakers: array of voice model IDs, one per speaker
  - `prosody` ProsodyControl: Controls for adjusting the prosody (rhythm and intonation) of generated speech.
    - `speed` number: Speaking rate multiplier. Valid range: 0.5 to 2.0. 1.0 = normal speed, 0.5 = half speed, 2.0 = double speed. Useful for adjusting pacing without regenerating audio.
    - `volume` number: Volume adjustment in decibels (dB). 0 = no change, positive values = louder, negative values = quieter.
    - `normalize_loudness` boolean: Normalize output loudness for more consistent perceived volume. Applies to the S2 family (`s2-pro`, `s2.1-pro`, `s2.1-pro-free`); on `s1` it is accepted but has no effect.
  - `chunk_length` integer: Text segment size for processing.
  - `normalize` boolean: 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, nullable: 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.
  - `format` 'wav' | 'pcm' | 'mp3' | 'opus': Output audio format.
  - `sample_rate` integer, nullable: Audio sample rate in Hz. When null, uses the format's default (44100 Hz for most formats, 48000 Hz for opus).
  - `mp3_bitrate` 64 | 128 | 192: MP3 bitrate in kbps. Only applies when format is mp3.
  - `opus_bitrate` -1000 | 24000 | 32000 | 48000 | 64000: Opus bitrate in bps. -1000 for automatic. Only applies when format is opus.
  - `latency` 'low' | 'normal' | 'balanced': Latency-quality trade-off. normal: best quality, balanced: reduced latency, low: lowest latency.
  - `max_new_tokens` integer: Maximum audio tokens to generate per text chunk.
  - `repetition_penalty` number: Penalty for repeating audio patterns. Values above 1.0 reduce repetition.
  - `min_chunk_length` integer: Minimum characters before splitting into a new chunk.
  - `condition_on_previous_chunks` boolean: Use previous audio as context for voice consistency.
  - `early_stop_threshold` number: Early stopping threshold for batch processing.
  - `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` union: Optional list of up to 3 pronunciation dictionaries to apply during synthesis. Provide either references to platform-managed dictionaries OR inline literal dictionaries (the two forms are mutually exclusive in a single request). The server resolves and merges the dictionaries, then forwards the full merged dictionary to the inference engine, which performs the substitution. Matching is plain substring matching, leftmost-longest, and case-insensitive unless an entry sets `case_sensitive`. Missing or unresolvable references are silently dropped — the request still succeeds. Use `application/json` or `application/msgpack` content-type; nested arrays are not representable in `multipart/form-data`.
    - PronunciationDictionaryRef[]: Reference form: list of pointers to platform pronunciation dictionaries. Each entry identifies a dictionary by `id` and `version`; the server resolves the contents from the platform service before forwarding them to the inference engine.
      - `id` string, required: Dictionary identifier as registered on the platform.
      - `version` string, required: Immutable version identifier for the dictionary. Version is required — there is no implicit `latest`.
    - PronunciationDictionaryInline[]: Inline form: list of literal pronunciation dictionaries. Each dictionary carries an `items` array of `{key, value, case_sensitive?}` entries.
      - `items` PronunciationItem[], required: Replacement entries for this dictionary. See the top-level `pronunciation_dictionary` field description for replacement semantics.
        - `key` string, required: Source substring to match. Pure substring match — no tokenization, no regex. Overlapping matches resolve leftmost-longest. For CJK text include enough context to disambiguate.
        - `value` string, required: Phonetic representation that replaces the key during synthesis. Dictionary authors should NOT include the `<|phoneme_start|>` / `<|phoneme_end|>` markers themselves; the inference engine wraps the value with those markers internally so the body is treated as phonemes rather than orthographic text. Requests whose key or value contain either marker are rejected.
        - `case_sensitive` boolean: When true the match is case-sensitive; when false ASCII case folding is applied.

## Response `200`

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.

## Other responses

- `401`: No permission -- see authorization schemes
- `402`: No payment -- see charging schemes
- `503`: The server cannot process the request due to a high load

## Changes

- **2026-11-03** `42ac421f7a12`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/fish/apis/fishaudio-openapi/changes/v1/tts/stream/with-timestamp/post.md)

---

[API](https://skmtc.dev/fish/apis/fishaudio-openapi.md) - [All operations](https://skmtc.dev/fish/apis/fishaudio-openapi/llms.txt) - [OpenAPI document](https://skmtc.dev/fish/apis/fishaudio-openapi/revisions/42ac421f7a12?raw)