Python SDK — Text-to-Speech

Overview

The SDK exposes three TTS clients — one per transport. They accept identical arguments and produce identical audio; they differ only in how quickly the first bytes reach you.

Class	Transport	Style	Use it for
`GnaniTTSClient`	REST	sync	Batch jobs, short strings, anything written to a file
`GnaniTTSStreamClient`	SSE	sync generator	Progressive playback without `asyncio`
`GnaniTTSRealtimeClient`	WebSocket	`async`	Conversational agents, lowest time-to-first-audio

from gnani.tts import GnaniTTSClient, GnaniTTSStreamClient, GnaniTTSRealtimeClient

Always pass model="timbre-v2.5". The SDK’s built-in default is still timbre-v2.0, which the API no longer serves — a call without an explicit model fails with 400 and The supported models are "timbre-v2.5". Every example on this page sets it explicitly.

REST — single response

Returns the complete audio as bytes. Pass output_file to also write it to disk; parent directories are created for you.

from gnani.tts import GnaniTTSClient

client = GnaniTTSClient()   # or GnaniTTSClient(api_key="your-api-key")

audio = client.synthesize(
    "नमस्ते, आप कैसे हैं?",
    voice="Nalini",
    model="timbre-v2.5",
    language="hi-IN",
    output_file="output.wav",
)

print(len(audio), "bytes")

Without output_file, handle the bytes yourself — upload them, return them from a web handler, or push them into an audio device.

audio = client.synthesize("Hello there", voice="Pranav", model="timbre-v2.5", language="en-IN")
return Response(audio, mimetype="audio/wav")

Parameters

Shared by all three clients unless noted.

Parameter	Type	Default	Description
`text`	`str`	required	The text to synthesize.
`voice`	`str`	`"Pranav"`	Voice ID. See Voices. Ignored when `speaker_embedding` is given.
`model`	`str`	`"timbre-v2.0"`	Set to `"timbre-v2.5"`.
`language`	`str`	`None`	BCP-47 code. `timbre-v2.5` only.
`speed`	`float`	`1.0`	Speaking rate, `0.85`–`1.15`. `timbre-v2.5` only.
`audio_config`	`AudioConfig`	48 kHz WAV	Output format. See Audio configuration.
`speaker_embedding`	`SpeakerEmbedding`	`None`	Cloned voice. See Voice cloning.
`output_file`	`str \| Path`	`None`	Write the audio here. Not available on `synthesize_stream()` / `synthesize()` on the realtime client.
`request_id`	`str`	auto	Custom ID for tracing.

Invalid combinations raise ValueError locally — an unknown voice for the model, speed out of range, or language/speed passed with a non-timbre-v2.5 model.

SSE — progressive playback

synthesize_stream() yields raw PCM chunks as they are generated, so playback can start before synthesis finishes. Chunks carry no WAV header.

from gnani.tts import GnaniTTSStreamClient

client = GnaniTTSStreamClient()

for chunk in client.synthesize_stream(
    "Your order has been confirmed and will arrive tomorrow.",
    voice="Kaveri",
    model="timbre-v2.5",
    language="en-IN",
):
    player.write(chunk)     # feed your audio device as bytes arrive

If you want a finished file instead, synthesize() collects every chunk and adds a RIFF header when the output is linear PCM WAV:

audio = client.synthesize(
    "Your order has been confirmed.",
    voice="Kaveri",
    model="timbre-v2.5",
    language="en-IN",
    output_file="confirmation.wav",
)

The header is added only for encoding="linear_pcm" with container="wav". For mp3, oggopus, or telephony encodings, the server’s bytes are returned untouched — those formats carry their own framing.

Realtime WebSocket — lowest latency

GnaniTTSRealtimeClient is async and offers three shapes, depending on how much control you need.

Stream chunks
Collect to a file
Typed events

synthesize() is an async generator of audio bytes. Use it when audio should start playing immediately.

import asyncio

from gnani.tts import GnaniTTSRealtimeClient


async def main():
    async with GnaniTTSRealtimeClient() as client:
        async for chunk in client.synthesize(
            "नमस्ते, मैं आपकी कैसे मदद कर सकता हूँ?",
            voice="Nalini",
            model="timbre-v2.5",
            language="hi-IN",
        ):
            await player.feed(chunk)


asyncio.run(main())

synthesize_and_collect() waits for the full response and returns it, with a WAV header when the output is linear PCM WAV.

import asyncio

from gnani.tts import GnaniTTSRealtimeClient


async def main():
    async with GnaniTTSRealtimeClient() as client:
        audio = await client.synthesize_and_collect(
            "नमस्ते, मैं आपकी कैसे मदद कर सकता हूँ?",
            voice="Nalini",
            model="timbre-v2.5",
            language="hi-IN",
            output_file="reply.wav",
        )


asyncio.run(main())

synthesize_events() yields typed events instead of bare bytes, so you can read chunk_index, detect the final chunk, and log the server’s request_id.

import asyncio

from gnani.tts import (
    GnaniTTSRealtimeClient,
    TTSAudioChunkEvent,
    TTSCompletedEvent,
    TTSStartEvent,
)


async def main():
    async with GnaniTTSRealtimeClient() as client:
        async for event in client.synthesize_events(
            "Your order has been confirmed.",
            voice="Pranav",
            model="timbre-v2.5",
            language="en-IN",
        ):
            if isinstance(event, TTSStartEvent):
                print(f"started — {event.request_id}")
            elif isinstance(event, TTSAudioChunkEvent):
                await player.feed(event.data)
                if event.is_final:
                    print("last audio chunk")
            elif isinstance(event, TTSCompletedEvent):
                print(f"done — {event.total_chunks} chunks")


asyncio.run(main())

Events

dataclass

The server has begun streaming audio.

Show Attributes

str

Identifier for this TTS request.

str

Status message from the server.

dataclass

One binary audio chunk.

Show Attributes

bytes

Raw audio bytes for this chunk.

int

Zero-based index within the response.

bool

True on the last audio-bearing chunk.

dataclass

Synthesis is finished and the connection is closing.

Show Attributes

str

Identifier for this TTS request.

int

Number of audio chunks sent.

Each call to synthesize(), synthesize_events(), or synthesize_and_collect() opens its own WebSocket connection and closes it when the server finishes. The async with block is for symmetry and future-proofing — it does not pool connections, so reusing one client instance across many calls is safe and cheap.

Audio configuration

AudioConfig controls the output format. The default is 48 kHz, 16-bit mono WAV.

from gnani.tts import AudioConfig, GnaniTTSClient

client = GnaniTTSClient()

audio = client.synthesize(
    "Your order has been confirmed.",
    voice="Pranav",
    model="timbre-v2.5",
    language="en-IN",
    audio_config=AudioConfig(sample_rate=48000, container="mp3", bitrate="128k"),
    output_file="confirmation.mp3",
)

Field	Type	Default	Accepted values
`sample_rate`	`int`	`48000`	`8000`, `16000`, `22050`, `24000`, `44100`, `48000`
`encoding`	`str`	`"linear_pcm"`	`linear_pcm`, `oggopus`, `pcm_mulaw`, `pcm_alaw`
`num_channels`	`int`	`1`	`1`–`8`
`sample_width`	`int`	`2`	`1`–`4` (bytes per sample)
`container`	`str`	`"wav"`	`raw`, `wav`, `mp3`, `ogg`, `mulaw`, `alaw`
`bitrate`	`str`	`None`	`32k`, `64k`, `96k`, `128k`, `192k` — MP3 only

Common presets

AudioConfig(sample_rate=48000, encoding="linear_pcm", container="wav")

AudioConfig(sample_rate=48000, container="mp3", bitrate="128k")

AudioConfig(sample_rate=8000, encoding="pcm_mulaw", container="mulaw")

AudioConfig(sample_rate=8000, encoding="pcm_alaw", container="alaw")

AudioConfig(encoding="oggopus", container="raw")

Unsupported values raise ValueError before the request is sent.

Voices

timbre-v2.5 offers 42 voices. Each has a preferred language — match voice to language for best quality.

Language	`language`	Voices
English	`en-IN`	Kaveri, Trupti, Devika, Pranav, Shlok, Girish
Hindi	`hi-IN`	Nalini, Bhavna, Yashvi, Urmila, Jwala, Chitra, Ambuja, Deepak, Roopesh, Vikrant, Hemraj, Jalaj, Omkar
Tamil	`ta-IN`	Asmita, Trisha, Brinda, Vedika, Noopur
Telugu	`te-IN`	Suhana, Lehara, Lavanya, Yukti, Varuni
Kannada	`kn-IN`	Saanvi, Kavin
Malayalam	`ml-IN`	Reshma, Riyaan
Marathi	`mr-IN`	Zahira, Ishaan
Bengali	`bn-IN`	Kirra, Dhruva
Gujarati	`gu-IN`	Falak, Veera
Punjabi	`pa-IN`	Mehuli, Zayan
Hinglish	`auto`	Poorvi

Query the list at runtime rather than hard-coding it:

from gnani.tts import GnaniTTSClient

GnaniTTSClient.supported_voices("timbre-v2.5")
# ["Ambuja", "Asmita", "Bhavna", ...]

Preview voices before integrating — open the Gnani TTS playground and filter by language, gender, and persona. Full descriptions are in the voice catalog.

Language and speed

Both are timbre-v2.5-only. Passing either with another model raises ValueError.

audio = client.synthesize(
    "आपका ऑर्डर कन्फर्म हो गया है।",
    voice="Nalini",
    model="timbre-v2.5",
    language="hi-IN",
    speed=1.1,              # 0.85 – 1.15
)

Accepted language values: auto, hi-IN, en-IN, ta-IN, te-IN, kn-IN, ml-IN, mr-IN, bn-IN, gu-IN, pa-IN. Use auto to detect the language from the input script — this is also what the Hinglish voice expects.

Voice cloning

Generate a speaker embedding with the voice-clone embeddings endpoint, then pass it as SpeakerEmbedding. When present, voice is ignored.

from gnani.tts import GnaniTTSClient, SpeakerEmbedding

embedding = SpeakerEmbedding(
    embedding=embedding_string,     # from POST /api/v1/tts/voice-clone/embeddings
    shape=[1, 768],
    dtype="torch.bfloat16",
)

audio = client.synthesize(
    "This is my cloned voice.",
    model="timbre-v2.5",
    speaker_embedding=embedding,
    output_file="cloned.wav",
)

SpeakerEmbedding works identically on all three clients.

Error handling

from gnani.tts import GnaniTTSClient
from gnani.tts.exceptions import APIError, GnaniTTSError

client = GnaniTTSClient()

try:
    audio = client.synthesize(
        "Hello there",
        voice="Pranav",
        model="timbre-v2.5",
        language="en-IN",
    )
except APIError as exc:
    print(f"API returned {exc.status_code}: {exc.body}")
except GnaniTTSError as exc:
    print(f"SDK error: {exc}")
except ValueError as exc:
    print(f"Invalid parameters: {exc}")

Exception	Raised when
`AuthenticationError`	No API key passed and `GNANI_API_KEY` unset.
`APIError`	Non-200 response. Carries `.status_code` and `.body`.
`StreamConnectionError`	The WebSocket handshake failed.
`StreamClosedError`	An operation was attempted on a closed stream.
`StreamError`	The server sent an error event mid-stream.
`ValueError`	Invalid voice, model, sample rate, container, bitrate, or speed — raised locally, before any request.

All except ValueError inherit from GnaniTTSError.

Gnani APIs

APIs

Use Cases

Python SDK — Text-to-Speech

Overview

REST — single response

Parameters

SSE — progressive playback

Realtime WebSocket — lowest latency

Events

Audio configuration

Common presets

Voices

Language and speed

Voice cloning

Error handling

Further Reading

​Overview

​REST — single response

​Parameters

​SSE — progressive playback

​Realtime WebSocket — lowest latency

​Events

​Audio configuration

​Common presets

​Voices

​Language and speed

​Voice cloning

​Error handling

​Further Reading

Overview

REST — single response

Parameters

SSE — progressive playback

Realtime WebSocket — lowest latency

Events

Audio configuration

Common presets

Voices

Language and speed

Voice cloning

Error handling

Further Reading