Dictate Best Practices
The code uses the
Sarvam Python and JavaScript SDKs (Python sarvamai 0.1.49 or later, JavaScript sarvamai 1.1.22 or later).
Every field and limit is in the API reference.
Dictate turns speech into text that a person can send: a chat message, a to-do list, a CRM record, meeting minutes. Pick the recipe that matches what you are building. New to Dictate? Make your first call first.
Recipes at a glance
How Dictate works
You send audio and some settings. Each setting answers one question:
mode: where does the text go?style.presetandstyle.rules: how tidy, and what form?vocabularyandcontext.reference: which names must be right?output_rules: what else do we need from the recording?
The Overview has the full table.
The one rule to remember: style.rules change the form of text. They never add or remove content.
When you need something new (an email, a summary, JSON), use output_rules.
The recipes below use all three routes: a clip, a job for long files, and the live socket.
Set up the client
The recipes use one client and two small helpers. Paste this at the top of your script:
dictate()opens a clip and sends it.fixes()prints thecorrectionsof a response.
The SDK sends style, vocabulary and context for you: pass them as plain dicts and lists (Python) or objects (JavaScript). It also waits and retries after a 429 by itself. See Handle errors and retries.
The recipes use short clips named after what they contain (voice_note.mp3, support_note.wav, and so on). Use a clip of your own with the same kind of content.
In JavaScript, call client.dictate.transcribe({ file: fs.createReadStream(clip), ...fields }) and pass the same objects. Fields keep the API names (language_code, output_rules, sounds_like).
Chat messages: choose the script
Use it when: the text goes to a chat, a document or a record, and the reader expects a certain script.
mode picks the script. Here is one Hindi clip in all four modes.
Send language_code when you know it. auto works, but a known language is more reliable.
Clean text: light or clean
Use it when: people say “um”, repeat words and correct themselves (“Tuesday, no sorry, Wednesday”), and you want to decide how much of that stays.
clean does not rewrite, and it cannot fix what speech recognition heard wrong.
Bullets, English, rupees and times
Use it when: you need a different layout, language or number format. A rule is a plain sentence in style.rules, and several rules can share one string, one sentence each.
Lists and translation
A Tamil to-do note, as bullets, as a checklist, and translated:
Money and times
English amounts already come in Indian digit grouping (1,25,000). A rule adds the sign and changes the clock:
Number words can stay as words in Telugu and Tamil. Add Write every number as digits. to get digits.
What a rule cannot do
A rule cannot add content: an email, a greeting, a summary or a shorter text. The words stay as the
person said them, so an app can paste text as the user’s own words. Use output_rules for those.
Names your way: vocabulary
Use it when: product, customer or medicine names must come out with your spelling. Speech recognition cannot know that your company is “Velqora” and a customer spells her name “Vyshnavi”.
corrections lists each change, so your app can show the user what changed. If recognition keeps writing a name wrong in the same way, copy that spelling from transcript into sounds_like:
Trap 1: a look-alike that was not said. If the list has a spelling variant of a name that was said, Dictate uses the listed spelling, even when recognition had it right. Here the list has “Draxiva” and “Harprit”, but the speaker said “Draxivo” and “Harpreet”.
Trap 2: the whole catalogue. A catalogue of 300 customer names in vocabulary fixed none of the three
names in the support note (0 of 3 in each of 4 runs). The same three names alone fixed all of them
(3 of 3 in each of 4 runs).
vocabulary corrects words that recognition wrote. It cannot bring back a word that recognition lost.
Names from a document: reference
Use it when: the names are already in a record you have (a meeting agenda, a CRM record, a prescription). Send it as it is, and Dictate takes the terms from it and uses them like a vocabulary. No list to build.
You can send both. When a term is in both, the vocabulary entry wins.
The situation: context.text
context.text tells the model what the recording is: “A support call about a broadband outage.” Use it to describe the situation in a sentence or two.
It can sometimes change how a name is spelled, but it is not reliable: the same text fixed a name in one run
and not in the next, and the change is not listed in corrections. Put names that must be right in
vocabulary or context.reference.
JSON, summaries and answers: output rules
Use it when: you need something new from the whole recording: JSON for a form, a summary, answers, a reply draft. You get it in output.text, next to the normal text. The output can only use what was said.
A sales call into a CRM record
Describe every key: its type, what it holds, and what to write when it was not said.
Answers to set questions
Give a way out for questions the call does not answer:
The output can only be as right as the text. A name that vocabulary fixed in text has the same spelling in output.
Long recordings: jobs
Use it when: the recording is longer than 30 s, up to 1 hour. Upload it, poll every 5 s, read result.output.text, then delete the job.
- Upload compressed audio (MP3, M4A, Opus). Files of about 100 MB or more are refused, so pass
audio_urlfor a large file. - Set a generous timeout for the upload:
SarvamAI(..., timeout=600)in Python, ortimeoutInSeconds: 600in JavaScript. For callbacks andaudio_url, see Transcribe long recordings. - Each POST is a new, billed job. Do not send it again without a reason.
For a callback instead of polling, pass callback={"url": ..., "auth_token": ...} to jobs.create. See Create Job.
The owner of a task is the weakest field in minutes. When two people speak in turn, the model can pick the
wrong one, or write the text “not mentioned” instead of null. Check this field in your app.
Live dictation: the socket
Use it when: the app shows partial text while the user speaks, then one finished text after each pause.
Send audio
send_audio with base64 audio: 16 kHz, mono, 16-bit, at most 1 s per message (0.5 s with stream_type=fast), at about real-time speed.
- To add a name in the middle of a session, call
update_configwithvocabulary. It applies from the next turn that ends, so it needs a pause between turns. - For push-to-talk, connect with
endpointing=manual. Each press is one turn, and only the pressed audio is billed. - Always call
endand read untilsession.end, or you lose the last turn and the output. - Open the socket from your server, not from a browser. The SDK sends your key as a header, which a browser socket cannot do.
- JavaScript on Node.js 22 and later: run the script with
node --no-experimental-websocket, or the socket is refused with403(the built-in WebSocket cannot send the key header). See Live dictation.
Cheat sheet
Check in every response: degraded (null means the finishing step ran), corrections (what names changed), and output.degraded when you send output_rules.
When something looks wrong
Find the group that matches what you see, then the row.
Text and names
Language and audio
Requests and limits
Jobs
Live socket
Limits to keep in mind
- Speech recognition comes first. No rule or preset fixes a word it heard wrong, so use
vocabularyfor the words you know. - Do sums yourself. Do arithmetic in your own code, and check task owners in meeting minutes.
- Results vary a little between runs. Check the text before you depend on it.
Limitations has the full list of what Dictate does not do, and its limits.