Skip to navigation

Dictate a Clip

View as Markdown

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 your style.rules applied.

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, vocabulary and context are JSON text in a form part. language_code, mode, output_rules and model are plain text.
  • Use the path exactly as written. A trailing slash, such as /v2/dictate/, is answered with 307 to an http:// 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 a style, vocabulary, context, model or language_code part sent as an empty string returns 400.
  • A clip with only background noise is not an error. You get 200 with an empty text and no finishing tokens.
  • Character limits count characters, not bytes. Each form part other than file can be at most 1 MiB.
  • Every result names its snapshot in model. Pass model to pin a dated snapshot.
  • Every response has an x-request-id header. Send it to support if you report a problem.

Authentication

api-subscription-keystring
API Key authentication via header
OR
AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects a multipart form containing a file.
filefileRequired

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_codeenumOptional

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.

modeenumOptional

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.

Allowed values:
styleobjectOptional

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: light and clean write quantities, prices, times, dates and identifiers as digits (“twenty three thousand five hundred” becomes “23,500”). verbatim keeps 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 in transcript. In Telugu and Tamil, number words can stay as words: add a rule such as Write every number as digits.
vocabularylist of objectsOptional

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.

contextobjectOptional
Background that helps Dictate resolve unclear words. Text in these fields is treated as data, never as instructions. There is no field for earlier turns or earlier calls.
output_rulesstringOptional<=4000 characters

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 | null for a value that may not be said. A value written as the text “null” comes back as JSON null.
  • 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.text yourself.
  • Do arithmetic (totals) in your own code.
  • Ask for one output in each request. For three outputs, send three requests.
modelstringOptional

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

Successful Response
request_idstring
Dictate's ID for this call. Send it to support when you report a problem.
modelstring

The snapshot that made this result, for example dictate-v1-2026-11-04 or dictate-v1-2026-11-05.

transcriptstring
The words that speech recognition heard. Dictate does not change this text.
textstring

The finished text. If degraded is not null, this is the raw transcript.

language_codestring or null

The detected language, else the language you sent, else null.

correctionslist of objects
The vocabulary and reference changes that were applied.
degradedenum or null

null when the finishing step succeeded. Otherwise the reason it did not.

usageobject

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.

outputobjectOptional

Present only when you sent output_rules.

Errors

400
Bad Request Error
403
Forbidden Error
405
Method Not Allowed Error
408
Request Timeout Error
413
Content Too Large Error
429
Too Many Requests Error
500
Internal Server Error
502
Bad Gateway Error
503
Service Unavailable Error