Introducing the Dictation API: the first API built for dictation

Output your users can send without editing it first

Most teams building dictation today start from a transcript and try to close the gap themselves. That work is harder than it looks. Deciding that “Tuesday, no wait, Wednesday” means Wednesday takes an understanding of what the speaker was doing, and so does knowing that a hesitation in the middle of a sentence should disappear while the person’s phrasing survives it. The Dictation API does that work as part of the request:

The first two rows happen by default. The third is the one teams underestimate: a name the model has never encountered is the most visible error in dictation, because the user always notices it and often can’t fix it faster than retyping the whole message. Pass the words your user cares about in keyterms_prompt and recognition biases toward those spellings. Teammates, customers, product names, internal jargon — the words a general-purpose model reliably mangles.

"keyterms_prompt": ["Sarai", "Q3 planning", "AssemblyAI"]

Universal-3.5 Pro is highly accurate out of the box, and contextual prompting is how you push it further for the cases that need it. The Dictation API inherits that capability whole. Pass the model a description of what it is about to hear in stt_prompt — your app, your domain, the kind of speech your users produce — and it uses that to guide the transcription. That is the difference between a transcript that is broadly right and one that gets your user’s vocabulary right.

The fourth row is the one you specify. Dictation into a Slack composer and dictation into a clinical note want different text out of the same sentence, and llm_instruction is where you draw that line:

"llm_instruction": "Format as a bulleted task list. Keep names verbatim."

Leave it out and you get the default cleanup. Either way the verbatim transcript comes back alongside it in text, so you always have both.

Under one second from key-up to finished text

Typical short clips come back in under one second. That number is not something you have to take on faith: every response carries request_time_ms, so the latency you see in production is the latency you can log from your first request onward.

You can also start the request before your user stops talking. The API accepts the audio in chunks as they’re captured, as long as the config part arrives first, so by the time someone releases the key most of their utterance is already uploaded.

Requests are bounded at five seconds. Past that bound the API returns a 200 with the verbatim text and llm_error: "timeout" rather than an error your client has to handle, which means the worst case your user experiences is plainer text than usual. That is a different thing from watching a spinner and losing the thought they were dictating.

Built on Universal-3.5 Pro, because a wrong word is unrecoverable

A misheard drug name, a mangled product name, or a wrong digit in a street address survives every improvement made downstream of it and ships straight out in whatever your user sends. Formatting is recoverable. Transcription errors are not.

That’s why the Dictation API runs on Universal-3.5 Pro, the same flagship model behind our async, realtime, and Sync surfaces. It ranks first for accuracy across independent benchmarks and posts a mean of 3.87% normalized word error rate on short-form audio, which is the audio profile dictation actually produces.

19 languages out of the box

Your users don’t all dictate in English, and the ones who don’t are the first to abandon a dictation feature that half-works. The Dictation API transcribes 19 languages, the same set Universal-3.5 Pro covers. Pass the ones your app supports in language_codes, which defaults to English.

"language_codes": ["en", "es", "de", "fr", "it", "pt", "tr", "nl", "sv", "no", "da", "fi", "hi", "vi", "ar", "he", "ja", "ur", "zh"]

How it works

Install the SDK, describe what the model is about to hear, and send the clip. Dictation accepts up to 120 seconds of audio per call.

pip install assemblyai

import assemblyai as aai

aai.settings.api_key = "<YOUR_API_KEY>"

config = aai.DictationConfig(
    stt_prompt="Dictation inside a project management tool. "
               "Expect task names, teammate names, and dates.",
    keyterms_prompt=["Sarai", "AssemblyAI", "Universal-3.5 Pro"],
)

result = aai.DictationTranscriber().transcribe_live("clip.wav", config)

print(result.llm_response)  # ready to paste at the cursor
print(result.text)          # verbatim, always present
print(result.final_text)    # the rewrite, falling back to the transcript

Underneath it is one POST with two multipart parts, a config JSON object and the audio, so any language with an HTTP client can call it the same way. transcribe_live() also takes an iterator of audio chunks, and open_live() takes audio pushed in from a callback, so you can start the upload while your user is still talking instead of waiting for the recording to finish. Both are in the Dictation docs.

Pricing

$0.62/hr of audio, all in. One line on your bill covers the whole request, so there is no second rate to model and no token math to do when you forecast what dictation costs at your volume. Volume discounts apply at any tier.

Blurt, an open-source dictation app built on it

We built a dictation app on the API and open-sourced the whole thing. Blurt is free, MIT-licensed, and native to macOS: hold right ⌘, talk, and the finished text lands in whatever app has focus. You bring your own API key, free tier included.

It’s also the quickest way to see the API working in a real app. Every feature in this post shows up somewhere in the code, so if you’re figuring out how to wire dictation into your own product, start there instead of from scratch.

blurt Try Blurt Blurt is a free Mac app that drops dictation into any text field on your machine. It runs on the Dictation API, so what you feel using it is what your users will feel. Mac only for now.

Get started

The Dictation API is available now at https://dictation.assemblyai.com/v1/transcribe/live with your existing API key. Send an utterance, read llm_response, paste it at the cursor. When you are ready to go further, the same request takes an stt_prompt describing your domain, keyterms_prompt for the names your users can’t afford to see misspelled, and an llm_instruction when the default output isn’t the shape your app needs.

Frequently asked questions