Quickstart

Overview

Send a spoken utterance in a single HTTP call and get back text your user can send as-is: filler gone, self-corrections resolved to what the speaker landed on, punctuation and capitalization applied, and the names and terms they care about spelled the way they spell them. The verbatim transcript always comes back alongside it, so you have both. Cleanup runs by default. With no configuration at all, the cleaned-up text arrives in llm_response and the words exactly as spoken arrive in text. Set llm_instruction when your app needs a particular shape instead, such as a bulleted task list or a clinical note. Dictation runs on Universal-3.5 Pro across 32 languages. The SDK accepts up to 120 seconds of audio per call, and you can start the request before the user stops talking, so most of the utterance is uploaded by the time they finish; see Uploading while recording. For a finished recording of up to 20 minutes, or a compressed format such as MP3, post it to POST /v1/transcribe over HTTP; see Transcribing a finished recording.

Python SDK

import assemblyai as aai

aai.settings.api_key = "<YOUR_API_KEY>"

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

print(result.text)  # verbatim transcript
print(result.llm_response)  # cleaned-up text, ready to send

Not using the SDK? The same flow works over plain HTTP — see Using the HTTP API directly.

Dictation is a separate service from Sync, Pre-recorded, and Streaming STT. It has its own hostname (dictation.assemblyai.com) and its own request shape. The Python SDK wraps it as DictationTranscriber; in every other language, call it over HTTP.

Before you begin

To complete this guide, you need:

An API key — browse to API Keys in your dashboard and copy your key.
An audio clip in WAV format, or raw 16-bit PCM. Maximum 120 seconds through the SDK, or 20 minutes over HTTP.
Python 3.8+ for the SDK. The HTTP examples lower down need Python 3.8+ with requests or httpx, Node.js 18+ with fetch, or cURL.

Send your first dictation

Step 1: Install the SDK

pip install -U assemblyai

Step 2: Run your first dictation

Save this as dictate.py, next to a clip.wav file of someone speaking:

import assemblyai as aai

aai.settings.api_key = "<YOUR_API_KEY>"

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

print("verbatim:", result.text)
print("cleaned: ", result.llm_response)

Then run it with python dictate.py. You get both versions back from the one call:

verbatim: Um, so, can you send me the Q3 numbers before the meeting tomorrow? Thanks.
cleaned:  So, can you send me the Q3 numbers before the meeting tomorrow? Thanks.

text is always what was said, word for word. llm_response is the cleaned-up version your user can send. Nothing had to be configured to get it: cleanup runs by default. transcribe_live() takes a file path, raw audio bytes, or an iterator of audio chunks. That last form is what lets you upload while the user is still speaking, covered in Uploading while recording.

Customize the request

Pass a config to change how the audio is transcribed, or to ask for a different shape of output. Every field is optional, and the SDK takes them as DictationConfig:

import assemblyai as aai

aai.settings.api_key = "<YOUR_API_KEY>"

config = aai.DictationConfig(
    stt_prompt="A doctor dictating a patient visit note.",
    keyterms_prompt=["amoxicillin", "lisinopril"],
    llm_instruction="Rewrite as a concise clinical chart note.",
    rewrite_mode="fast",
)

result = aai.DictationTranscriber().transcribe_live("clip.wav", config)
print(result.final_text)  # the rewrite, falling back to the transcript

Over HTTP the same fields go in the config part of the request body, described in Using the HTTP API directly.

Config parameters

Every field except llm_instruction and rewrite_mode controls transcription. Those two customize the transcript rewrite, which is applied by default — see Rewriting the transcript.

Field	Type	Meaning
`sample_rate`	integer	Sample rate of the audio. Required for raw PCM (for example `16000`). Ignored for WAV — the sample rate is read from the file header.
`channels`	integer	Channel count. Required for raw PCM.
`language_codes`	array of strings	Language(s) of the audio as ISO codes. See Language selection for the full list. When omitted, no language steering is applied.
`stt_prompt`	string	Context for the transcription: a description of what the audio is about, such as `"A doctor dictating a patient visit note."` (max 6000 characters). It describes the situation rather than instructing the model, and is prepended to the base transcription prompt, which always applies. Also accepted as `prompt` — send one or the other, or the request is rejected with `400`.
`keyterms_prompt`	array of strings	Terms to bias transcription toward, such as names or jargon (max 100 terms / 8000 characters total). Same parameter name as the Streaming and Pre-recorded APIs. The legacy names `keyterms` and `word_boost` are also accepted — send only one of the three, or the request is rejected with `400`.
`llm_instruction`	string	Plain-English description of the rewrite you want. Replaces the default cleanup task; omit it to keep the default. See Rewriting the transcript.
`rewrite_mode`	string	Model tier that runs the rewrite: `fast` (the default) or `smart`, which follows detailed formatting instructions more reliably but has higher latency. See Choosing a rewrite mode.

Unknown fields are rejected with a 400 rather than ignored, so a typo surfaces as an error instead of a setting that quietly does nothing.

Rewriting the transcript

Cleanup is applied by default. Omitting llm_instruction, or the whole config part, runs the default cleanup task: filler comes out, self-corrections resolve to what the speaker landed on, and punctuation and capitalization are applied. The speaker’s own phrasing and tone survive it. To ask for a different shape instead, set llm_instruction to a plain-English description of the task you want. It replaces the default cleanup task:

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

The rewrite never replaces the transcription. text is always the verbatim transcript, and the rewritten version arrives separately in llm_response. See Transcript rewriting for how to write a good instruction, what the service enforces for you, and why dictated commands are never carried out.

Uploading while recording

You don’t have to wait for the recording to finish. The endpoint reads the body as it arrives, so you can open the request while the user is still speaking and send audio as it is captured. See Uploading while recording.

What you get back

A successful call returns 200 with JSON:

Field	Type	Meaning
`text`	string	The verbatim transcript. Never altered by the LLM.
`words`	array	Per-word objects `{ text, confidence }`.
`confidence`	number	Overall transcription confidence, 0–1.
`llm_response`	string or `null`	The rewritten text. `null` when the rewrite failed.
`llm_error`	string or `null`	`"timeout"` or `"error"` when the rewrite failed.
`audio_duration_ms`	number	Duration of the submitted audio.
`session_id`	string	Request identifier. Include it when reporting problems.
`request_time_ms`	number	Total server-side processing time.
`sync_time_ms`	number	Transcription portion of `request_time_ms`.
`auth_time_ms`	number	Authentication portion of `request_time_ms`.

Rewrites are best-effort. A rewrite failure still returns 200 with the transcription. If llm_response is null and text is present, use text. Never treat a non-null llm_error as a failed request.

Errors

Errors come in two body shapes. Auth failures (401), rate limiting (429), and errors from the transcription step, such as an unknown config field or an unsupported audio format (415), return {"status", "title", "detail"}. Errors Dictation raises itself, such as a malformed request, audio over the limit (413), capacity (503), and upstream failures (502, 504), return {"error", "error_code"}. Read both shapes. Set the HTTP client timeout to 90 seconds. Typical short clips respond in under one second. The rewrite has an internal deadline; past it, the response returns with llm_error: "timeout" and the transcription intact. See Error handling for the full status code table and retry guidance.

Using the HTTP API directly

The SDK wraps a single HTTP request. Call it directly from any language.

Endpoints

Dictation has two transcription endpoints. Choose by whether the audio is still being recorded when you send it:

	`POST /v1/transcribe/live`	`POST /v1/transcribe`
Use for	Audio still being recorded, uploaded as it is captured	A finished recording you hold in full
Maximum duration	120 seconds	20 minutes
Maximum size	256 MB	256 MB
Formats	WAV or raw 16-bit PCM	WAV, raw 16-bit PCM, AAC, MP3, M4A, Ogg/Opus, FLAC, or WebM
`config` part	Required, sent before `audio`	Optional, in any order
SDK	`DictationTranscriber`	HTTP only

Both return the same response. The rest of this section covers /v1/transcribe/live; see Transcribing a finished recording for /v1/transcribe.

POST https://dictation.assemblyai.com/v1/transcribe/live

Send the parts in order — config first, then audio. The endpoint reads the body as it arrives, so you can start the request while the user is still speaking and upload the audio as it is captured; see Uploading while recording. /v1/transcribe/stream is the path this endpoint shipped under and still reaches the same handler. There is no unversioned alias.

Authentication

Pass your AssemblyAI API key in the Authorization header as the raw key, with no Bearer prefix:

Authorization: <YOUR_API_KEY>

A missing or invalid API key returns 401 Unauthorized with a {"status", "title", "detail"} body: {"status": 401, "title": "Unauthorized", "detail": "Invalid API key"} when the key is wrong, and "Missing Authorization header" when there is no key at all.

Request body

The body is multipart/form-data with two parts, in this order:

Part	Content
`config` (required)	A JSON object (Content-Type `application/json`). See Config parameters. Send `{}` to transcribe with defaults, including the default rewrite.
`audio` (required)	The audio bytes. Set the part’s Content-Type to `audio/wav` for WAV or `audio/pcm` for raw 16-bit PCM. Maximum 120 seconds of audio.

Config comes first, and is required, because the server starts transcribing the audio as it arrives and cannot begin without it. An audio part that arrives before config, or a request with no config part at all, is rejected with 400. WAV and raw PCM only. This endpoint decodes audio as it arrives, and compressed formats (MP3, M4A, FLAC, OGG, WebM) cannot be decoded incrementally, so they are rejected with 415. Decode them to WAV or PCM before sending.

Making the request

Python
JavaScript
cURL

import requests

with open("clip.wav", "rb") as f:
    audio = f.read()

response = requests.post(
    "https://dictation.assemblyai.com/v1/transcribe/live",
    headers={"Authorization": "<YOUR_API_KEY>"},
    files={
        # `config` first, and always present — `{}` means "no settings".
        "config": (None, "{}", "application/json"),
        "audio": ("clip.wav", audio, "audio/wav"),
    },
    timeout=90,
)
response.raise_for_status()
result = response.json()

print(result["text"])  # verbatim transcript
print(result["llm_response"])  # cleaned-up text, ready to send

import { readFileSync } from "fs";

const audio = readFileSync("clip.wav");
const form = new FormData();
// `config` first, and always present — `{}` means "no settings".
form.append("config", new Blob(["{}"], { type: "application/json" }));
form.append("audio", new Blob([audio], { type: "audio/wav" }), "clip.wav");

const response = await fetch("https://dictation.assemblyai.com/v1/transcribe/live", {
  method: "POST",
  headers: { Authorization: "<YOUR_API_KEY>" },
  body: form,
});

if (!response.ok) {
  const error = await response.json();
  throw new Error(error.error || error.detail);
}

const result = await response.json();
console.log(result.text); // verbatim transcript
console.log(result.llm_response); // cleaned-up text, ready to send

curl -X POST https://dictation.assemblyai.com/v1/transcribe/live \
  -H 'Authorization: <YOUR_API_KEY>' \
  -F 'config={};type=application/json' \
  -F 'audio=@clip.wav;type=audio/wav'

Transcribing a finished recording

POST https://dictation.assemblyai.com/v1/transcribe

For a recording you already hold in full, post it to /v1/transcribe. It accepts audio from 80 milliseconds up to 20 minutes and 256 MB, and the response is the same as /v1/transcribe/live’s, rewrite included. The server reads the whole body before it starts transcribing, so the request is simpler:

config is optional and can come before or after audio. Leave it out to transcribe with defaults, including the default rewrite.
Compressed formats are accepted. Set the audio part’s Content-Type to the format: audio/wav, audio/pcm, audio/aac, audio/mpeg (MP3), audio/mp4 (M4A), audio/ogg (Ogg/Opus), audio/flac, or audio/webm. Raw PCM still needs sample_rate and channels in config.
Nothing is transcribed until the upload finishes, so for audio that is still being recorded, /v1/transcribe/live returns sooner.

The SDK uses /v1/transcribe/live, so call this endpoint over HTTP. It is also served at /transcribe, without the version prefix.

Python
cURL

import requests

with open("recording.mp3", "rb") as f:
    audio = f.read()

response = requests.post(
    "https://dictation.assemblyai.com/v1/transcribe",
    headers={"Authorization": "<YOUR_API_KEY>"},
    files={"audio": ("recording.mp3", audio, "audio/mpeg")},
    timeout=90,
)
response.raise_for_status()
result = response.json()

print(result["text"])          # verbatim transcript
print(result["llm_response"])  # cleaned-up text, ready to send

curl -X POST https://dictation.assemblyai.com/v1/transcribe \
  -H 'Authorization: <YOUR_API_KEY>' \
  -F 'audio=@recording.mp3;type=audio/mpeg'

Next steps

Uploading while recording — start the request before the speaker stops
Examples — end-to-end requests for a clinical note and a travel booking
Transcript rewriting — reshape the transcript with llm_instruction
Prompting and keyterms — steer the transcript with context and exact terms
Language selection — transcribe in one or more of 32 languages
Audio requirements — duration, sample width, and format constraints
Error handling — status codes and retry guidance
Cloud endpoints & data residency — global routing and the US/EU data zones
Connection pre-warming — take the TLS handshake off the critical path
API reference — the full request and response schema

Getting started

Features

API reference

Advanced

Overview

Before you begin

Send your first dictation

Step 1: Install the SDK

Step 2: Run your first dictation

Customize the request

Config parameters

Rewriting the transcript

Uploading while recording

What you get back

Errors

Using the HTTP API directly

Endpoints

Authentication

Request body

Making the request

Transcribing a finished recording

Next steps

​Overview

​Before you begin

​Send your first dictation

​Step 1: Install the SDK

​Step 2: Run your first dictation

​Customize the request

​Config parameters

​Rewriting the transcript

​Uploading while recording

​What you get back

​Errors

​Using the HTTP API directly

​Endpoints

​Authentication

​Request body

​Making the request

​Transcribing a finished recording

​Next steps

Overview

Before you begin

Send your first dictation

Step 1: Install the SDK

Step 2: Run your first dictation

Customize the request

Config parameters

Rewriting the transcript

Uploading while recording

What you get back

Errors

Using the HTTP API directly

Endpoints

Authentication

Request body

Making the request

Transcribing a finished recording

Next steps