Skip to main content
POST
TTS Inference

Overview

New — Audio Tags: Add expressive delivery on Timbre v3.0 by placing tags like <whispers>, <laugh>, or <pauses> inline in your text.
Get the complete synthesized audio in one response. Best for downloads or batch processing. For streaming playback, see TTS Streaming or 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.

Response

A successful request returns 200 OK with raw binary audio in the format specified by audio_config.container. Errors: Text-to-Speech and Voice Cloning (REST and SSE) return errors in a flat body, not the error.type envelope used by Speech-to-Text:
Authentication and rate-limit errors use the shape shown below. Some validation failures on the embeddings endpoint can also return 422 with a {"detail": [...]} body. Authentication and rate-limit errors do not use the success / error envelope. They look like this:
The same shapes are returned by REST, Batch, Text-to-Speech, Voice Cloning and the Realtime handshake (as an HTTP response before the WebSocket opens). See Error Reference for all Speech API errors.

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 official Python SDK handles authentication headers and binary audio responses automatically.

Installation

Requires Python 3.10+.

Authentication

Synthesize Speech

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 audio synthesis

The response is of type file.