Dictate a Clip
Turns a recording of up to 30 seconds into text a person can paste, and returns it in the same response.
Each call returns two texts:
transcript: the words that speech recognition heard, unchanged.text: the finished version, with punctuation, no fillers or false starts, numbers as digits, your names spelled your way, and yourstyle.rulesapplied.
Add output_rules to also get one output made from the whole recording, such as a summary or a JSON record.
The finishing step never fails the call. If it fails or is too slow, text is the raw transcript and degraded tells you why.
Other routes: for a recording up to 1 hour, use POST /v2/dictate/jobs. For live audio, use the /v2/dictate/ws WebSocket. For recipes and how-to guides, see Dictate best practices.
Good to know
- Send
multipart/form-data.style,vocabularyandcontextare JSON text in a form part.language_code,mode,output_rulesandmodelare plain text. - Use the path exactly as written. A trailing slash, such as
/v2/dictate/, is answered with307to anhttp://address, and a client that follows it sends your request and key without encryption. - Send every option as a form part. A query parameter, such as
?language_code=hi-IN, is ignored, and it does not return an error. - Leave a field out to keep its default.
null, an unknown field, a repeated field, or astyle,vocabulary,context,modelorlanguage_codepart sent as an empty string returns400. - A clip with only background noise is not an error. You get
200with an emptytextand no finishing tokens. - Character limits count characters, not bytes. Each form part other than
filecan be at most 1 MiB. - Every result names its snapshot in
model. Passmodelto pin a dated snapshot. - Every response has an
x-request-idheader. Send it to support if you report a problem.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Request
Audio of 30 seconds or less, up to 10,000,000 bytes, not empty. Formats: WAV, MP3, AAC, AIFF, OGG, Opus, FLAC, MP4/M4A, AMR, WMA and WebM, found from the MIME type or the file content.
Language of the audio. auto (default) detects Hindi, Bengali, Kannada, Malayalam, Marathi, Odia, Punjabi, Tamil, Telugu, English and Gujarati. For Assamese, Urdu, Nepali, Konkani, Kashmiri, Sindhi, Sanskrit, Santali, Manipuri, Bodo, Maithili and Dogri, send the code: they are accepted and give text in the language’s own script, but their quality is not fully evaluated yet. Codes are case-sensitive; Odia is or-IN.
With auto, the language_code in the result is the detected language, and a clip with only noise comes back with a null language_code. If you know the language, send it: with auto, some speech comes back in a different script or in English.
A code that does not match the audio is not an error: the text comes back in that language’s script. English audio sent as hi-IN returns the English words written in Devanagari, with degraded null and no warning.
Script of the finished text and how literal it is.
transcribe(default): keeps the script that speech recognition wrote.codemix: writes the language in its own script, and English words and names in Latin letters, the way people type Hinglish or Tanglish.translit: writes everything in Latin letters, for example Hindi as Roman Hindi. Use it for apps that show Latin letters only.verbatim: keeps every sound, filler and repeat, and keeps numbers as words. Use it for exact records. A recognition loop (the same words 3 or more times in a row) can be removed.
There is no translate mode. To translate, ask for it in style.rules.
How the finished text is written. style has no other members: prefix and suffix return 400.
- Layout: line breaks, paragraphs and lists appear only where the speaker said them (“new line”, “first … second …”) or where a rule asks for them. They are made inside each clip or job section.
- Numbers:
lightandcleanwrite quantities, prices, times, dates and identifiers as digits (“twenty three thousand five hundred” becomes “23,500”).verbatimkeeps number words. - Indian languages: outside Hindi, digits are best effort. Some numbers stay words, and a converted value can be wrong. Outside
verbatim, speech recognition also writes digits, so a wrong value can already be intranscript. In Telugu and Tamil, number words can stay as words: add a rule such asWrite every number as digits.
Up to 1,000 names and terms. Dictate finds the terms that match each piece of text, and does not send the whole list to the model. Send the names of this recording (this customer, this team, this product line), not your full catalogue. Do not add names that will not be said: a listed term can be written in place of a similar name that was said. Do not send a whole catalogue: in testing, a list of 300 names fixed none of the three names in a recording, while a list of just those three fixed all of them.
Asks for one output made from the whole recording, for example a summary, a SOAP note, answers to questions or a JSON record. Write what you want in plain words, in any language, up to 4,000 characters. The output is made in one model call at the end that reads these rules and the whole finished text (the raw transcript for a part that is degraded), so a name that your vocabulary fixed in text has the same spelling in output. It does not change transcript or text. An empty string, or a string of only spaces, means no output.
To get a good output:
- Name every key of a JSON output, say what it means and whose value it is (“
buyer_phone: the buyer’s phone number; the buyer asks for the product”). - Use
string | nullfor a value that may not be said. A value written as the text “null” comes back as JSONnull. - Say the format you need: digits for prices, Latin letters for names, a language for the answer. For Indian-language audio, write “Write every value in English” once at the top, or “in English” in each key’s description. With no language named, the values come back in the speaker’s script.
- Keep JSON to one or two levels, and parse
output.textyourself. - Do arithmetic (totals) in your own code.
- Ask for one output in each request. For three outputs, send three requests.
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 and is kept for at least 90 days after notice of its retirement. A snapshot fixes the speech recognition model, the finishing model and both prompts. An unknown name returns 400, and the message lists the names you can use.
Served now: dictate-v1-2026-11-04 and dictate-v1-2026-11-05. On most clips they give the same text. They differ only in how some numbers are written. In testing, when the speaker said “March fifth”, dictate-v1-2026-11-04 wrote “March 5th” and dictate-v1-2026-11-05 wrote “5 March”. For “five hundred fifty thousand rupees”, dictate-v1-2026-11-04 wrote “5,50,000 rupees” and dictate-v1-2026-11-05 wrote “₹5,50,000”. Both use Indian digit grouping. dictate-v1-2026-11-05 also sends about 16% more input tokens to the finishing model. Pin a dated snapshot when your code parses the text and it must not change without notice.
Response
The snapshot that made this result, for example dictate-v1-2026-11-04 or dictate-v1-2026-11-05.
The finished text. If degraded is not null, this is the raw transcript.
The detected language, else the language you sent, else null.
null when the finishing step succeeded. Otherwise the reason it did not.
Billed: audio that was recognised and finished, silence included. Not billed: a failed call or job, a degraded clip, and the degraded sections of a job. A repeated request is billed again. With output_rules, the output’s tokens are included in the token counts here and also shown in output.usage.
Present only when you sent output_rules.