WebSocket
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
- Connect to
wss://api.sarvam.ai/v2/dictate/wswith your key in theapi-subscription-keyheader. A key in the URL query string is refused with403. 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. - Read
session.begin. If you want, send aconfig.updatewithstyle,vocabulary,contextoroutput_rules. - Send audio at about real-time speed. Show
transcript.partialas a preview, then replace the turn with itsdictation.final. - Send
endand keep reading untilsession.end. If you close the socket withoutend, results that are not yet sent are lost.
Settings
language_code,mode,modeland the audio settings go in the URL. An unknown or wrong URL setting returns HTTP 400 before the upgrade.style,vocabulary,contextandoutput_rulesgo in aconfig.updatemessage.keytermsandpromptare refused: usevocabularyinstead.
Good to know
- Turn order:
utterance_idxstarts at 0 and counts turns. Each kind of final message arrives in turn order, but atranscript.finalfor a later turn can arrive before thedictation.finalof an earlier turn. Match them byutterance_idx. Each turn gets exactly onedictation.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
vocabularywithconfig.updateonce it is said. - Push-to-talk: use
endpointing=manualand sendspeech_startandspeech_end. - Quiet sockets: send
pingduring 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.*andpongmessages, never the final ones. - Output: with
output_rules, theoutput.finalevent comes after the lastdictation.finaland beforesession.end. The output call can take up to 90 s.
Close codes
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
Headers
Query parameters
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 languagehi-IN: Hindibn-IN: Bengalikn-IN: Kannadaml-IN: Malayalammr-IN: Marathior-IN: Odiapa-IN: Punjabita-IN: Tamilte-IN: Teluguen-IN: Englishgu-IN: Gujaratias-IN: Assameseur-IN: Urdune-IN: Nepalikok-IN: Konkaniks-IN: Kashmirisd-IN: Sindhisa-IN: Sanskritsat-IN: Santalimni-IN: Manipuribrx-IN: Bodomai-IN: Maithilidoi-IN: Dogri
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.
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.
How turns end. Fixed for the session.
- vad (default): Dictate finds the end of each turn.
- manual: You send
speech_startandspeech_end.
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.
Encoding of the raw audio you send. Mono only, with no file
header. linear16 is signed 16-bit little-endian.
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).
When true, adds start_s and end_s to transcript.final.
Speech detection threshold, from 0 to 1. Applies with endpointing=vad.
Shortest speech, in ms, that counts as a turn. Applies with endpointing=vad.
The pause, in ms, that ends a turn. Applies with endpointing=vad.
Audio, in ms, kept before the detected start of speech. Applies with endpointing=vad.
Send
Start a turn (endpointing=manual only)
End the turn (endpointing=manual only)
End the turn, same as speech_end
Receive
Receive speech start and end events (endpointing=vad only)
Receive speech start and end events (endpointing=vad only)