Stream speech over WebSocket

WSS wss://api.vakyam.ai/v1/tts/websocket

Real-time, sentence-by-sentence synthesis. Authenticate with the Authorization header on connect, send a config message, then one text message per sentence. See the realtime guide for the full message reference.

Ask AI about this page

Authorization

header Authorizationstringrequired

Bearer token sent on connect: Bearer vak_live_<key>. An invalid key closes the connection with code 4001.

Messages you send

Every client message is a JSON object with a type field. Send config first, then one text per sentence. Send cancel to interrupt the current utterance, ping to keep the socket alive, and disconnect to close cleanly.

Sets the session voice, language, model, format, and speed. Must be the first message after connecting.

123456789{
  "type": "config",
  "model_id": "raaga-v1",
  "voice": "Archana",
  "language": "ta-IN",
  "output_format": "pcm",
  "sample_rate": 24000,
  "speed": 1.0
}

body typestringrequired

Always config.

body model_idstringrequired

Model identifier. Must be raaga-v1.

body voicestringrequired

Voice selector. A preset voice name (e.g. Archana) or a custom voice ID beginning with vc_. A preset voice must form a valid pair with language. Send either voice or the deprecated voice_name, not both.

body voice_namestringdeprecated

Deprecated — use voice instead. Temporarily accepted for preset voices only.

body languagestringrequired

BCP 47 language code: en-IN, hi-IN, ta-IN, te-IN, kn-IN, mr-IN, gu-IN, or bn-IN.

body output_formatstringdefault: pcm

Audio format: pcm, mp3, wav, or mulaw. Defaults to pcm over WebSocket to avoid container overhead.

body sample_rateintegerdefault: 24000

Output sample rate in Hz. One of 8000, 16000, 24000, or 48000.

body speednumberdefault: 1.0

Playback speed multiplier, 0.5–2.0.

Messages you receive

Between configured and end_of_utterance, the server streams the audio as raw binary WebSocket frames (not JSON). Reassemble them in arrival order. All other server messages are JSON objects with a type field.

Sent once after the connection is authenticated.

1234{
  "type": "connected",
  "user_id": "f1e2d3c4-..."
}

typestring

Always connected.

user_idstring

The authenticated account's ID.

Idle timeout

Idle connections close automatically after 60 seconds without an incoming message. Any message you send — including a ping — resets the timer, so send a periodic ping to keep a session open between utterances. The Python and JavaScript SDKs send a keepalive ping for you by default.

Close codes

Code	Reason
1000	Normal closure
1011	Session lost (concurrency or worker capacity revoked mid-session) — reconnect
4001	Authentication failed
4002	Internal server error

Handshake

wss

1234wss://api.vakyam.ai/v1/tts/websocket

Header   Authorization: Bearer vak_live_<key>
Status   101 Switching Protocols

Messages sent

12345678{
  "type": "config",
  "model_id": "raaga-v1",
  "voice": "Archana",
  "language": "ta-IN",
  "output_format": "pcm",
  "speed": 1.0
}

Messages received

1234{
  "type": "connected",
  "user_id": "f1e2d3c4-..."
}