Create Job
Starts a job for a recording up to 1 hour long, and returns a job_id at once.
- Create the job here, with a
fileor anaudio_urlthat Dictate downloads. - Read the result with
GET /v2/dictate/jobs/{job_id}, or pass acallbackto be told when the job is finished. - Delete the job with
DELETE /v2/dictate/jobs/{job_id}when you have the result. Results are kept for 7 days.
For a full example that turns a recording into meeting minutes, see Dictate best practices.
Good to know
- 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
multipart/form-datawith aContent-Lengthheader. Chunked uploads are not accepted. 202means the job is saved, not finished. A rule broken in the text ofaudio_urlorcallback.urlreturns400at once. A DNS or download problem appears later as aFailedjob.- Dictate measures the audio when it processes the job, so a file over 1 hour is accepted with
202and then fails withaudio_too_long. - The job keeps the model snapshot it was accepted with.
- Character limits count characters, not bytes. Each form part other than
filecan be at most 1 MiB. - There is no route to list jobs or to stop a job, so keep the
job_idfrom this response. - Each POST makes a new job, and it is billed. There is no idempotency key, so do not send a POST again to retry a poll.
- 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 up to 1 hour long, in any common audio or video format. Dictate takes the first audio track. Dictate itself accepts files up to 1,000,000,000 bytes, but the gateway in front of it refuses an upload of about 100 MB or more with 413 (the body can be empty), and a slow connection can be cut off with no status. For a large file, use audio_url. Set a client timeout on the upload: a stalled upload through the gateway gets no answer.
An https URL that Dictate downloads, on port 443 or 8443, with no user name or password, that does not point to a private, loopback or internal address. It can redirect up to 3 times. The host must let Dictate download the file: some public hosts refuse its downloader with 403, and the job then fails as fetch_failed. A URL that is not https, that uses localhost, or that is a private or loopback IP address such as https://10.0.0.5/..., is refused at create with 400. Any other host name is checked when the job runs: a name that resolves to a private address, or that does not resolve, gives 202, and the job then ends Failed with invalid_audio_url.
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.
Where Dictate sends a POST when the job is Completed or Failed. The body is {"job_id": "...", "job_state": "Completed"} (or "Failed") and does not contain the result: read it with GET /v2/dictate/jobs/{job_id}. A delivery succeeds on a 2xx answer within 10 s. Any other answer, a redirect included (Dictate does not follow it), or no answer in 10 s is a failed delivery, and Dictate retries after 5 s, 30 s, 2 min, 10 min, 30 min and 1 h. The same callback can arrive more than once.
Response
Accepted: saved and in the queue.Pending: back in the queue after a temporary internal problem.Running: a worker is processing it.Completed:resultis ready.Failed:errortells why.