Skip to navigation

Dictate API

View as Markdown

The SDK examples use the pre-release SDKs: sarvamai 0.1.49a1 for Python and 1.1.22-alpha.1 for JavaScript. The install commands are in the Quickstart.

Sarvam Dictate is a dictation API that turns audio into the text a person meant to type, in English and 22 Indian languages. One call pairs Saaras v4, Sarvam’s ASR model, which hears the audio and writes the transcript, with Sarvam 105B. Sarvam 105B reads that transcript together with context from your app: a vocabulary of the user’s names and terms, a document such as a CRM record or product list, a line about the situation, and a style. It returns the finished text next to the raw transcript and can apply up to 1000 keyterms.

Want to try it right now? Jump to the quickstart.

See it work

Drop the “um”, the repeats and the false starts, and keep the corrected version. This is the default.

You say
Um, let's meet on Tuesday, no sorry, Wednesday at the main office.
Dictate returns in text
Let's meet on Wednesday at the main office.

Every example here was produced by running the code on the live API. The recipes show the code for each one.

What you can build

Which route should I use?

Pick the route by the audio you have.

Your audioRouteYou get
A file of 30 seconds or lessClip
POST /v2/dictate
The text in the response
A file of up to 1 hourJob
POST /v2/dictate/jobs
A job to poll, or a callback
A live microphoneLive socket
WSS /v2/dictate/ws
Partial text while the person speaks, then one finished text after each pause

Not sure? Start with a clip. It is the shortest path, and the quickstart below uses it.

Quickstart

1

Get a key and install the SDK

Create an API key on the dashboard and set it as SARVAM_API_KEY. Dictate reads the key from the api-subscription-key header or from Authorization: Bearer <key>: either one is enough. You need Python 3.8 or later, or Node.js 18 or later.

pip install "sarvamai==0.1.49a1"
2

Get a test clip

Any recording of 30 s or less works: WAV, MP3, M4A and more. Record your own, or make one with the tool for your system:

Use Sarvam’s own text to speech. It needs the SDK and SARVAM_API_KEY from step 1.

import base64, os
from sarvamai import SarvamAI
client = SarvamAI(
api_subscription_key=os.environ["SARVAM_API_KEY"],
)
audio = client.text_to_speech.convert(
text=(
"Um, let's meet on Tuesday, no sorry, "
"Wednesday at the main office."
),
language_code="en-IN",
model="bulbul:v3",
speech_sample_rate=16000,
)
with open("note.wav", "wb") as f:
f.write(base64.b64decode(audio.audios[0]))
3

Make your first call

Use POST /v2/dictate.

import os
from sarvamai import SarvamAI
client = SarvamAI(api_subscription_key=os.environ["SARVAM_API_KEY"])
with open("note.wav", "rb") as f:
response = client.dictate.transcribe(file=f, language_code="en-IN")
print(response.text) # the finished text
print(response.transcript) # what speech recognition heard
print(response.degraded) # None when the text was finished
Response (trimmed)
{
"text": "Let's meet on Wednesday at the main office.",
"transcript": "um, let's meet on Tuesday. No sorry, Wednesday at the main office.",
"degraded": null,
"corrections": [],
"usage": { "audio_duration_s": 4.01, "words": 12, "llm_input_tokens": 5366, "llm_output_tokens": 12 }
}

What you get back

FieldWhat it isUse it for
textThe finished textShow it to people
transcriptWhat speech recognition heard, unchangedSearch and audit
correctionsEach name that vocabulary or context.reference changedShow the user what changed
degradednull when the finishing step ran. Otherwise the reason it did not, and text is the raw transcriptCheck it in every response
outputA new text made from the whole recording. Only when you send output_rulesJSON for a form, a summary, a reply
usageAudio length in seconds, word count and model tokens. It has no price: work out the cost from the audio length and your per-minute priceCost tracking

Customize the request

Each setting answers one question. Leave a field out to keep its default.

QuestionSettingGuide
What language is it?language_code: one of 23 codes, or autoAudio and languages
Where does the text go: a chat, a document, a record?mode: codemix, transcribe, translit or verbatimChoose the script
How much do we tidy it?style.preset: none, light or cleanBest Practices
What form must the text have: bullets, English, ₹?style.rulesChange the form
Which names must be right?vocabulary, context.referenceGet names right
What else do we need from the recording?output_rulesGet JSON, summaries and answers
Must the text stay the same over time?model: pin a dated snapshotPin a model version

Dictate or Speech-to-Text?

Both turn speech into text. Choose by what the text is for.

Here is the same recording through each.

Speech-to-Text (Saaras) returns
Um, so I was, I was thinking that we could, you know, like maybe go there tomorrow and and see the place.
Dictate returns
So I was thinking that we could maybe go there tomorrow and see the place.
DictateSpeech-to-Text (Saaras)
What you getFinished text a person can send: punctuation, no “um” or false starts, numbers as digitsThe transcript of what was said, in the mode you pick
Your names and rulesvocabulary and context.reference fix names. style.rules set the form (bullets, English, ₹)Keyterm prompting. No style rules
A new text from the recordingoutput_rules gives JSON, a summary, answers or a replyNo
Long audioA job: up to 1 hourBatch: up to 2 hours, up to 20 files per job
Live audioWebSocket: partial text while speaking, then one finished text for each pauseRealtime: partial transcripts for voice agents, with config.update and VAD tuning

Use Dictate when the text goes straight to a person or a system: a chat message, a note, a CRM record or form, meeting minutes. The finishing, the names and the JSON are done for you.

Use Speech-to-Text (Saaras) when you need the raw transcript, for search or analytics, or the longest files, or a voice agent that reacts to partial transcripts while the user is still speaking.

You can use both: keep the Speech-to-Text transcript for your records, and use Dictate for the text you show.

What Dictate doesn’t do

If you are comparing APIs, check this list first. Dictate does not offer:

  • Subtitle files. There is no SRT or VTT output.
  • Browser tokens. There are no short-lived tokens, so a browser or app cannot open the socket safely. Open it from your server.
  • Translation as a mode. There is no translate mode. Ask for it in style.rules.

Limitations lists every limit.

Pricing and rate limits

  • Price. Dictate costs ₹0.50 per minute of audio on Pay as you go, and less on Pro, Growth and Business. Every response has a usage field with the audio length in seconds (audio_duration_s) and the token counts. It does not show an amount, so multiply the minutes by your price. All prices are on the pricing page.
  • Rate limits. They are the same as Speech-to-Text, and are listed under Dictate limits.
  • Over a limit. The API answers 429 with a Retry-After header. The SDKs wait and try again by themselves. See Handle errors and retries.

Next steps