API Guides & TutorialsText to Speech

Streaming Text-to-Speech API

WebSocket-based streaming endpoint that sends audio chunks progressively as text is processed. Connect once, stream text in, receive audio out — no polling, no repeated HTTP calls.

Common use cases:

  • Conversational AI agents — Stream TTS responses in real time for voice-based assistants
  • Interactive podcasts — Generate and play back dialogue on the fly with minimal delay
  • Low-latency applications — Any scenario where time-to-first-byte (TTFB) matters (IVR, live narration, kiosks)

Why WebSocket Streaming

Low Latency Playback

Audio playback begins as soon as the first chunk is synthesized — no need to wait for the full response.

11 Languages (10 Indian + English)

Hindi, Bengali, Tamil, Telugu, Kannada, Malayalam, Marathi, Gujarati, Punjabi, Odia, and English (Indian accent).

Persistent Connection

Single WebSocket connection handles multiple text to speech conversions. Send config once, then stream text continuously.

SDK Support

Python (AsyncSarvamAI) and JavaScript (SarvamAIClient) SDKs with built-in async/await and event-driven patterns for seamless integration.

Code Examples

Best Practices

  • Always send the config message first
  • Use flush messages strategically to ensure complete text processing
  • Send ping messages to maintain long-running connections
1import asyncio
2import base64
3from sarvamai import AsyncSarvamAI, AudioOutput
4
5async def tts_stream():
6    client = AsyncSarvamAI(api_subscription_key="YOUR_SARVAM_API_KEY")
7
8    async with client.text_to_speech_streaming.connect(model="bulbul:v3") as ws:
9        await ws.configure(target_language_code="hi-IN", speaker="shubh")
10        print("Sent configuration")
11
12        long_text = (
13            "भारत की संस्कृति विश्व की सबसे प्राचीन और समृद्ध संस्कृतियों में से एक है।"
14            "यह विविधता, सहिष्णुता और परंपराओं का अद्भुत संगम है, "
15            "जिसमें विभिन्न धर्म, भाषाएं, त्योहार, संगीत, नृत्य, वास्तुकला और जीवनशैली शामिल हैं।"
16        )
17
18        await ws.convert(long_text)
19        print("Sent text message")
20
21        await ws.flush()
22        print("Flushed buffer")
23
24        chunk_count = 0
25        with open("output.mp3", "wb") as f:
26            async for message in ws:
27                if isinstance(message, AudioOutput):
28                    chunk_count += 1
29                    audio_chunk = base64.b64decode(message.data.audio)
30                    f.write(audio_chunk)
31                    f.flush()
32
33        print(f"All {chunk_count} chunks saved to output.mp3")
34        print("Audio generation complete")
35
36
37        if hasattr(ws, "_websocket") and not ws._websocket.closed:
38            await ws._websocket.close()
39            print("WebSocket connection closed.")
40
41
42if __name__ == "__main__":
43    asyncio.run(tts_stream())
44
45# --- Notebook/Colab usage ---
46# await tts_stream()

End of Speech Signal

The TTS streaming API now supports an end of speech signal that allows for clean stream termination when speech generation is complete.

Using send_completion_event

When you set send_completion_event=True in the connection, the API will send a completion event when speech generation ends, allowing your application to handle stream termination gracefully.

Python
1import asyncio
2import base64
3from sarvamai import AsyncSarvamAI, AudioOutput, EventResponse
4
5
6async def tts_stream():
7    client = AsyncSarvamAI(api_subscription_key="YOUR_SARVAM_API_KEY")
8
9    async with client.text_to_speech_streaming.connect(
10        model="bulbul:v3", send_completion_event=True
11    ) as ws:
12        await ws.configure(
13            target_language_code="hi-IN",
14            speaker="shubh",
15        )
16        print("Sent configuration")
17
18        long_text = (
19            "भारत की संस्कृति विश्व की सबसे प्राचीन और समृद्ध "
20            "संस्कृतियों में से एक है।"
21            "यह विविधता, सहिष्णुता और परंपराओं का अद्भुत संगम है, "
22            "जिसमें विभिन्न धर्म, भाषाएं, त्योहार, संगीत, नृत्य, "
23            "वास्तुकला और जीवनशैली शामिल हैं।"
24        )
25
26        await ws.convert(long_text)
27        print("Sent text message")
28
29        await ws.flush()
30        print("Flushed buffer")
31
32        chunk_count = 0
33        with open("output.mp3", "wb") as f:
34            async for message in ws:
35                if isinstance(message, AudioOutput):
36                    chunk_count += 1
37                    audio_chunk = base64.b64decode(message.data.audio)
38                    f.write(audio_chunk)
39                    f.flush()
40                elif isinstance(message, EventResponse):
41                    print(f"Received completion event: {message.data.event_type}")
42                    # Break when we receive the final event
43                    if message.data.event_type == "final":
44                        break
45
46        print(f"All {chunk_count} chunks saved to output.mp3")
47        print("Audio generation complete")
48
49
50if __name__ == "__main__":
51    asyncio.run(tts_stream())
52
53# --- Notebook/Colab usage ---
54# await tts_stream()

Streaming TTS WebSocket – Integration Guide

Easily convert text to speech in real time using Sarvam’s low-latency WebSocket-based TTS API.

Input Message Types

Sets up voice parameters and must be the first message sent after connection. Parameters:

  • min_buffer_size: Minimum character length that triggers buffer flushing for TTS model processing
  • max_chunk_length: Maximum length for sentence splitting (adjust based on content length)
  • output_audio_codec: Supports multiple formats: mp3, wav, aac, opus, flac, pcm (LINEAR16), mulaw (μ-law), and alaw (A-law)
  • output_audio_bitrate: Choose from 5 supported bitrate options
1{
2  "type": "config",
3  "data": {
4    "speaker": "shubh",
5    "target_language_code": "en-IN",
6    "pace": 1.2,
7    "min_buffer_size": 50,
8    "max_chunk_length": 200,
9    "output_audio_codec": "mp3",
10    "output_audio_bitrate": "128k"
11  }
12}