Skip to main content
POST
TTS Stream

Overview

New — Audio Tags: Add expressive delivery on Timbre v3.0 by placing tags like <whispers>, <laugh>, or <pauses> inline in your text.
Receive audio in chunks as it’s generated, allowing playback to start immediately. Reduces latency compared to TTS REST. For the lowest latency, see TTS Realtime.
Passing numbers, IDs, dates, or currency as raw strings causes mispronunciations. See the Input Formatting Guide for correct formatting of phone numbers, account numbers, PINs, Aadhaar, vehicle registration numbers, GSTIN, currency, and more.

Models

Supported languages: Hindi, English, Tamil, Telugu, Kannada, Malayalam, Marathi, Punjabi, Bengali, and Gujarati. Each model has its own voices — see the Voice Catalog.

Endpoint


Authentication


Request Parameters

string
required
The text to synthesize into speech. Pass numbers, dates, and currency as spoken words to avoid mispronunciations — see Input Formatting Guide.
string
required
timbre-v2.5 or timbre-v3.0. The model determines which voices you can use.
string
required
Voice name from the catalog of the model you selected — voices are not shared between models.
string
required
Language of the input text. Controls text normalization and routing.
number | string
default:"1.0"
Playback speed multiplier. Numeric range: 0.85 (slowest) to 1.15 (fastest). String shortcuts: "slow" = 0.85, "medium" = 1.0, "fast" = 1.15.
object
Controls the format of the returned audio.

Audio Format Reference

Encoding aliases — produce identical output to the container rows above: bitrate only applies when container=mp3. container=mulaw/alaw override sample_rate to 8000 Hz.
When container=ogg or encoding=oggopus is requested, all audio chunks are encoded into a single OGG Opus file delivered as one chunk — streaming delivery is not possible for OGG.

Response

The server streams audio via Server-Sent Events. Each chunk event carries base64-encoded audio in the audio field. A final complete event signals that synthesis is finished.

Errors

Text-to-Speech (WebSocket error message, and the error event on SSE) uses type and message:
The connection remains open after recoverable errors. Voice Cloning (WebSocket) adds an error code:

Code Example


Available Voices

Each model has its own voices, and a voice only works with its own model:
  • Timbre v2.5 — 42 voices across 10 Indian languages, English, and Hinglish, each with a preferred language. See Timbre v2.5 voices.
  • Timbre v3.0 — 13 voices that each speak all 10 languages and support audio tags. See Timbre v3.0 voices.
Popular examples: Nalini (Hindi), Kaveri (English), Deepak (Hindi), Poorvi (Hinglish).

Python SDK

The SDK’s streaming client handles SSE parsing and chunk reassembly for you — you just iterate and write.

Installation

Requires Python 3.10+.

Authentication

Stream Audio to a File

synthesize_stream yields audio chunks as they arrive. Playback or writing can begin before the full response is complete.

With Custom Audio Config

Authorizations

X-API-Key-ID
string
header
required

Headers

X-API-Key-ID
string
required

Body

application/json

Request body for TTS inference.

text
string
required

Text to synthesize. With timbre-v3.0 the text may carry inline audio tags: <coughs>, <excited>, <exhales>, <giggle>, <laugh>, <pauses>, <shouting>, <sigh>, <slow>, <sniffles>, <whispers>, <yawns>, <clears throat> — for example Let me check. <pauses> Found it <laugh>. With timbre-v2.5 these tags are removed before synthesis and are not spoken; text consisting only of tags is rejected with 400.

model
enum<string>
required

TTS model: timbre-v2.5 or timbre-v3.0. Each model has its own voice catalog, and a voice from one cannot be used with the other. timbre-v3.0 additionally supports inline audio tags in text.

Available options:
timbre-v2.5,
timbre-v3.0
audio_config
AudioConfig · object
required

Audio output configuration.

voice
string

Voice name from the catalog of the requested model. timbre-v3.0 voices: Avinash, Shivani, Lakshmi, Kalpana, Shubham, Prakash, Devansh, Yashraj, Chetana, Vasudha, Riyaa, Tarika and Harshad (each speaks all supported languages).

language
string

Language code. Use auto, hi-IN, en-IN, hi-en, ta-IN, te-IN, kn-IN, ml-IN, mr-IN, pa-IN, bn-IN, or gu-IN.

speed
number

Playback speed multiplier. Range: 0.85–1.15.

Response

Successful Server-Sent Events stream

The response is of type string.