Skip to navigation

WebSocket

View as Markdown

Live dictation over a WebSocket. For each turn (speech ended by a pause), Dictate streams the raw transcript while the person speaks, then sends one finished text (dictation.final). For a full example, see the Dictate best practices.

How a session goes

  1. Connect to wss://api.sarvam.ai/v2/dictate/ws with your key in the api-subscription-key header. A key in the URL query string is refused with 403. Open the socket from your server: a browser WebSocket cannot set headers, and a long-lived key must not go in a browser or app.
  2. Read session.begin. If you want, send a config.update with style, vocabulary, context or output_rules.
  3. Send audio at about real-time speed. Show transcript.partial as a preview, then replace the turn with its dictation.final.
  4. Send end and keep reading until session.end. If you close the socket without end, results that are not yet sent are lost.

Settings

  • language_code, mode, model and the audio settings go in the URL. An unknown or wrong URL setting returns HTTP 400 before the upgrade.
  • style, vocabulary, context and output_rules go in a config.update message. keyterms and prompt are refused: use vocabulary instead.

Good to know

  • Turn order: utterance_idx starts at 0 and counts turns. Each kind of final message arrives in turn order, but a transcript.final for a later turn can arrive before the dictation.final of an earlier turn. Match them by utterance_idx. Each turn gets exactly one dictation.final, also when it fails.
  • Long speech: with endpointing=vad, about 18 to 20 s of speech with no pause ends a turn, even inside a word. Each part is finished on its own, so a number or URL across the cut is split.
  • No memory between turns: there is no field for earlier turns. To carry a name to later turns, add it to vocabulary with config.update once it is said.
  • Push-to-talk: use endpointing=manual and send speech_start and speech_end.
  • Quiet sockets: send ping during long silences. The socket closes after 60 s with no message from you.
  • Recognition: the socket uses the live recogniser, not the clip recogniser, so the same audio can give different words on the two routes. A client that reads too slowly can lose transcript.partial, vad.* and pong messages, never the final ones.
  • Output: with output_rules, the output.final event comes after the last dictation.final and before session.end. The output call can take up to 90 s.

Close codes

CodeMeaning
1000Normal end, after end.
1002WebSocket protocol error.
1007A text message is not valid UTF-8.
1008No message from you for 60 s, or the 3-hour session limit.
1009A message is larger than 1 MiB.
1011Recognition stopped, or a settings change was not confirmed in 5 s. Also sent with the reason keepalive ping timeout when your client stops answering the server’s pings, for example because it stopped reading. This happens in under a minute.
1012The service is restarting. Dictate finishes your open turns and sends session.end when it can. Connect again to continue.
1013Recognition is overloaded, or your client did not read messages for 60 s.

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.

Handshake

WSS
wss://api.sarvam.ai/v2/dictate/ws

Headers

Api-Subscription-KeystringRequired
API subscription key for authentication

Query parameters

language_codeenumOptionalDefaults to auto

Language of the audio. auto (default) detects Hindi, Bengali, Kannada, Malayalam, Marathi, Odia, Punjabi, Tamil, Telugu, English and Gujarati. For the other languages, send the code. Codes are case-sensitive; Odia is or-IN.

  • auto: Detect the language
  • hi-IN: Hindi
  • bn-IN: Bengali
  • kn-IN: Kannada
  • ml-IN: Malayalam
  • mr-IN: Marathi
  • or-IN: Odia
  • pa-IN: Punjabi
  • ta-IN: Tamil
  • te-IN: Telugu
  • en-IN: English
  • gu-IN: Gujarati
  • as-IN: Assamese
  • ur-IN: Urdu
  • ne-IN: Nepali
  • kok-IN: Konkani
  • ks-IN: Kashmiri
  • sd-IN: Sindhi
  • sa-IN: Sanskrit
  • sat-IN: Santali
  • mni-IN: Manipuri
  • brx-IN: Bodo
  • mai-IN: Maithili
  • doi-IN: Dogri
modeenumOptionalDefaults to transcribe

Script of the finished text and how literal it is.

  • transcribe (default): Keeps the script that speech recognition wrote.
  • verbatim: Keeps every sound, filler and repeat, and keeps numbers as words. Use it for exact records.
  • translit: Writes everything in Latin letters. Use it for apps that show Latin letters only.
  • codemix: Writes the language in its own script, and English words and names in Latin letters, the way people type Hinglish or Tanglish.
Allowed values:
modelstringOptionalDefaults to dictate-v1

The model snapshot to use. dictate-v1 (default) is an alias for dictate-v1-2026-11-04; it moves to a newer snapshot after 30 days’ notice. A dated snapshot never changes. Served now: dictate-v1-2026-11-04 and dictate-v1-2026-11-05, which differ only in numbers. Fixed for the session.

endpointingenumOptionalDefaults to vad

How turns end. Fixed for the session.

  • vad (default): Dictate finds the end of each turn.
  • manual: You send speech_start and speech_end.
Allowed values:
stream_typeenumOptionalDefaults to balanced

Latency of the live preview.

  • fast: Partials at low latency. Each audio message can hold at most 0.5 s.
  • balanced (default): Partials with better accuracy.
  • simulated: No partials.
Allowed values:
encodingenumOptionalDefaults to linear16

Encoding of the raw audio you send. Mono only, with no file header. linear16 is signed 16-bit little-endian.

Allowed values:
sample_rateenumOptionalDefaults to 16000

Sample rate of the audio in Hz. Must match the audio. Dictate does not check it and measures the audio at the rate you declare, so 16 kHz audio sent as 8000 raises no error, the text is wrong, and the billed seconds double. Other values are refused when you connect (400).

Allowed values:
return_timestampsenumOptionalDefaults to false

When true, adds start_s and end_s to transcript.final.

Allowed values:
thresholdstringOptionalDefaults to 0.3

Speech detection threshold, from 0 to 1. Applies with endpointing=vad.

min_speech_duration_msstringOptionalDefaults to 250

Shortest speech, in ms, that counts as a turn. Applies with endpointing=vad.

silence_duration_msstringOptionalDefaults to 1000

The pause, in ms, that ends a turn. Applies with endpointing=vad.

prefix_padding_msstringOptionalDefaults to 300

Audio, in ms, kept before the detected start of speech. Applies with endpointing=vad.

Send

Dictate Audio InputobjectRequired
Send an audio chunk for live dictation
OR
Dictate Speech StartobjectRequired

Start a turn (endpointing=manual only)

OR
Dictate Speech EndobjectRequired

End the turn (endpointing=manual only)

OR
Dictate FlushobjectRequired

End the turn, same as speech_end

OR
Dictate Config UpdateobjectRequired
Change style, vocabulary, context or other session settings
OR
Dictate End SessionobjectRequired
Finish the open turn and end the session
OR
Dictate PingobjectRequired
Keep a quiet socket open

Receive

Dictate Session BeginobjectRequired
Receive session.begin after the connection opens
OR
Dictate Config UpdatedobjectRequired
Receive config.updated after a config.update takes effect
OR
Dictate VAD EventsobjectRequired

Receive speech start and end events (endpointing=vad only)

OR
Dictate VAD EventsobjectRequired

Receive speech start and end events (endpointing=vad only)

OR
Dictate Partial TranscriptobjectRequired
Receive the live preview of the raw text
OR
Dictate Final TranscriptobjectRequired
Receive the raw text of a turn
OR
Dictate Final TextobjectRequired
Receive the finished text of a turn
OR
Dictate Output FinalobjectRequired
Receive the output made from the whole session
OR
Dictate PongobjectRequired
Receive the answer to a ping
OR
Dictate Session EndobjectRequired
Receive session.end, the last message after end
OR
Dictate ErrorobjectRequired
Receive an error