WebSocket
WebSocket channel for real-time TTS synthesis.
Note: This API Reference page is provided for informational purposes only. The Try It playground may not provide the best experience for streaming audio. For optimal streaming performance, please use the SDK or implement your own WebSocket client.
Connecting
- Open
wss://api.sarvam.ai/text-to-speech/wsand authenticate with theApi-Subscription-Keyheader (orAuthorization: Bearer <key>). Browsers cannot set headers on a WebSocket, so pass the key as the subprotocolapi-subscription-key.<key>instead. A missing or invalid key is rejected with HTTP 403 during the handshake, and the key cannot be sent as a query parameter. - Choose the model with the
modelconnection query parameter (bulbul:v3orbulbul:v4-flash). If omitted,bulbul:v3is used. - Add
send_completion_event=trueto receive afinalevent after each flush. It is off by default.
Message flow
- Send a
configmessage first. Sendingtextbeforeconfigreturns an error. - Send one or more
textmessages (up to 2,500 characters each). - Send
flushto synthesize any text still in the buffer. Audio arrives asaudiomessages, followed by aneventmessage if completion events are on. - Repeat steps 2 and 3 for more utterances on the same connection. A new
configmessage updates the settings and flushes the current buffer first.
Keeping the connection open
- The server closes an idle connection after 60 seconds with an
errormessage (code 408) and a normal close. Send apingmessage to keep it open. The server does not reply to pings.
Both models
bulbul:v3andbulbul:v4-flashuse the same messages and accept the same settings: pitch -0.5 to 0.5, loudness 0.1 to 2.5, pace 0.5 to 2.0, temperature 0.01 to 1.0. Default sample rate: 22050 Hz.
Handshake
Headers
Query parameters
Text to speech model to use. Set it as the model query parameter on the connection URL.
- bulbul:v4-flash: the latest model, recommended for new integrations. Same messages as bulbul:v3, with 200+ persona voices.
- bulbul:v3: the API default when omitted. 37 named speakers.
Set it as the send_completion_event query parameter on the connection URL. When true, an event message with event_type final is sent after the last audio chunk of each flush. Default is false, and it has no effect when sent inside a config message.
Send
Send initial configuration for text-to-speech streaming
Receive
Receive completion event notifications from the TTS WebSocket (if send_completion_event is enabled)