Skip to navigation

WebSocket

View as Markdown

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/ws and authenticate with the Api-Subscription-Key header (or Authorization: Bearer <key>). Browsers cannot set headers on a WebSocket, so pass the key as the subprotocol api-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 model connection query parameter (bulbul:v3 or bulbul:v4-flash). If omitted, bulbul:v3 is used.
  • Add send_completion_event=true to receive a final event after each flush. It is off by default.

Message flow

  1. Send a config message first. Sending text before config returns an error.
  2. Send one or more text messages (up to 2,500 characters each).
  3. Send flush to synthesize any text still in the buffer. Audio arrives as audio messages, followed by an event message if completion events are on.
  4. Repeat steps 2 and 3 for more utterances on the same connection. A new config message updates the settings and flushes the current buffer first.

Keeping the connection open

  • The server closes an idle connection after 60 seconds with an error message (code 408) and a normal close. Send a ping message to keep it open. The server does not reply to pings.

Both models

  • bulbul:v3 and bulbul:v4-flash use 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

WSS
wss://api.sarvam.ai/text-to-speech/ws

Headers

Api-Subscription-KeystringRequired
API subscription key for authentication

Query parameters

modelenumOptionalDefaults to bulbul:v3

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.
Allowed values:
send_completion_eventenumOptionalDefaults to false

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.

Allowed values:

Send

Configure ConnectionobjectRequired

Send initial configuration for text-to-speech streaming

OR
Send TextobjectRequired
Send text chunk for speech synthesis
OR
Flush SignalobjectRequired
Send signal to end text streaming.
OR
Ping SignalobjectRequired
Send ping signal to keep the TTS WebSocket connection alive.

Receive

Audio OutputobjectRequired
Receive audio chunks from the TTS WebSocket.
OR
Event NotificationobjectRequired

Receive completion event notifications from the TTS WebSocket (if send_completion_event is enabled)

OR
Error ResponseobjectRequired
Receive error messages from the TTS WebSocket