> ## Documentation Index
> Fetch the complete documentation index at: https://assemblyai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Transcribe dictated audio
## OpenAPI
````yaml specs/dictation.yaml POST /v1/transcribe/live
openapi: 3.1.0
info:
title: AssemblyAI Dictation API
description: >-
Short-form dictation that returns a verbatim transcript together with an
LLM-rewritten version of it, in a single HTTP call.
version: 1.0.0
servers:
- url: https://dictation.assemblyai.com
description: Global (default — routes to nearest region)
- url: https://dictation.us.assemblyai.com
description: US data residency (us-east-1, us-east-2, us-west-1, us-west-2)
- url: https://dictation.eu.assemblyai.com
description: >-
EU data residency (eu-central-1, eu-north-1, eu-south-1, eu-south-2,
eu-west-1, eu-west-3)
security:
- ApiKey: []
paths:
/v1/transcribe/live:
post:
summary: Transcribe dictated audio
description: |
Send an audio clip and receive the verbatim transcript together with an
LLM-rewritten version of it. Audio must be at most 120 seconds.
The rewrite runs by default. With no configuration it removes
disfluencies and leaves every other word exactly as spoken. Set
`llm_instruction` to describe a different transformation, such as a
chart note or a booking confirmation. The verbatim transcript is always
returned in `text` alongside the rewrite in `llm_response`.
The body is `multipart/form-data` with two parts, and the `config` part
must arrive **before** the `audio` part. The server begins transcribing
the audio as it arrives and cannot start without the config, so a body
whose audio comes first, or that has no config part at all, is rejected
with `400`. Send `{}` when you have no options to set.
Because the server reads the body as it arrives, you can open the
request while the user is still speaking and upload the audio as it is
captured. What the user then waits for after they stop speaking is the
last stretch of audio rather than the whole clip. See
[Uploading while recording](/dictation#uploading-while-recording).
This endpoint is also served at `/v1/transcribe/stream`, the path it
shipped under. There is no unversioned alias.
Dictation is a separate service from Sync, Pre-recorded, and
Streaming STT, with its own hostname (`dictation.assemblyai.com`) and
its own request shape. The Python SDK wraps it as `DictationTranscriber`
from version 1.5.1; in every other language, call it over HTTP. See the
[Dictation API guide](/dictation) for full guidance.
operationId: transcribeDictation
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- config
- audio
properties:
config:
type: object
additionalProperties: true
description: >-
Transcription and rewrite configuration. Must be the first
part, ahead of `audio`. Send an empty object (`{}`) to
transcribe with defaults, including the default rewrite.
Unknown fields are forwarded to the transcription engine
as-is, so transcription parameters added in future work
without dictation-side changes.
properties:
sample_rate:
type: integer
description: >-
Source sample rate in Hz, for example `16000`. Required
when `audio` is `audio/pcm`. Ignored for WAV, which
carries its sample rate in the file header.
channels:
type: integer
description: >-
Number of audio channels. Required when `audio` is
`audio/pcm`. Ignored for WAV.
language_codes:
type: array
default:
- en
items:
type: string
enum:
- en
- es
- de
- fr
- it
- pt
- tr
- nl
- sv
- 'no'
- da
- fi
- hi
- vi
- ar
- he
- ja
- ur
- zh
description: >-
Language or languages of the audio, as ISO 639-1 codes.
Defaults to `["en"]`.
stt_prompt:
type: string
maxLength: 6000
description: >-
Context for the transcription: a description of what the
audio is about, such as "A doctor dictating a patient
visit note." 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:
type: array
maxItems: 100
items:
type: string
description: >-
Terms to bias transcription toward, such as names or
jargon. Maximum 100 terms and 8000 characters in total.
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:
type: string
maxLength: 2048
nullable: true
description: >-
Plain-English description of the rewrite you want, which
replaces the default cleanup task. Describe only the
transformation: rules about output format, refusing to
answer the text, and handling clean input are enforced
automatically. Omitting the field, or setting it to
`null`, keeps the default cleanup task, which removes
disfluencies and changes nothing else.
audio:
type: string
format: binary
description: >-
Audio bytes, at most 120 seconds. Set the part's
Content-Type to `audio/wav` for WAV or `audio/pcm` for raw
16-bit PCM. Compressed formats (MP3, M4A, FLAC, OGG, WebM)
are rejected with `415`. The part may be uploaded in chunks
as the audio is captured.
encoding:
config:
contentType: application/json
audio:
contentType: audio/wav, audio/pcm
responses:
'200':
description: >-
Transcription completed. The rewrite is best-effort: a failed
rewrite still returns `200` with the transcription, `llm_response`
set to `null`, and `llm_error` set. Fall back to `text` in that
case, and never treat a non-`null` `llm_error` as a failed request.
content:
application/json:
schema:
$ref: '#/components/schemas/DictationResponse'
example:
text: >-
Um, patient presents with, uh, a persistent cough for about
two weeks.
words:
- text: Um
confidence: 0.82
- text: patient
confidence: 0.97
- text: presents
confidence: 0.96
confidence: 0.94
llm_response: Patient presents with a persistent cough for about two weeks.
llm_error: null
audio_duration_ms: 5120
session_id: eb92c4ff-4bbb-429f-9b99-7279d7fe738f
request_time_ms: 812.4
sync_time_ms: 430.1
'400':
description: >-
Missing or empty `audio` part, a missing `config` part or one sent
after `audio`, malformed `config` JSON, or a `config` field that
fails validation.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: No credential supplied.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: >-
Invalid API key. This endpoint returns `404` rather than `401` for a
bad key, so treat any `404` as an auth failure.
content:
application/json:
schema:
$ref: '#/components/schemas/DetailErrorResponse'
example:
status: 404
title: Not Found
detail: Invalid API key
'413':
description: >-
The audio exceeded the size cap. On a chunked upload this can arrive
mid-request, with `error_code` set to `audio_too_large`.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'415':
description: >-
The `audio` part is not `audio/wav` or `audio/pcm`. Relayed from the
transcription service, so the body uses the
`status`/`title`/`detail` shape rather than `error`/`error_code`.
content:
application/json:
schema:
$ref: '#/components/schemas/DetailErrorResponse'
'429':
description: Rate limited. Back off and retry.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'502':
description: >-
Transcription upstream unavailable. Retry once, then surface an
error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'503':
description: >-
Server at capacity, with `error_code` set to `capacity_exceeded`.
Back off and retry.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'504':
description: Transcription upstream timed out. Retry once, then surface an error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-codeSamples:
- lang: python
label: Python SDK
source: >
import assemblyai as aai
aai.settings.api_key = ""
result = aai.DictationTranscriber().transcribe_live("clip.wav")
print(result.text) # verbatim transcript
print(result.llm_response) # default cleanup rewrite
print(result.final_text) # the rewrite, falling back to the
transcript
- lang: bash
label: cURL
source: |
curl -X POST https://dictation.assemblyai.com/v1/transcribe/live \
-H 'Authorization: ' \
-F 'config={};type=application/json' \
-F 'audio=@clip.wav;type=audio/wav'
- lang: python
label: Python
source: |
import requests
with open("clip.wav", "rb") as f:
audio = f.read()
response = requests.post(
"https://dictation.assemblyai.com/v1/transcribe/live",
headers={"Authorization": ""},
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"]) # default cleanup rewrite
- lang: javascript
label: JavaScript
source: >
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: "" },
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); // default cleanup rewrite
components:
schemas:
DictationResponse:
type: object
required:
- text
- words
- confidence
- audio_duration_ms
- session_id
properties:
text:
type: string
description: The verbatim transcript. Never altered by the LLM.
words:
type: array
items:
$ref: '#/components/schemas/Word'
description: Per-word transcript objects.
confidence:
type: number
format: float
description: Overall transcription confidence (0–1).
llm_response:
type: string
nullable: true
description: >-
The rewritten text, or `null` when the rewrite failed. Fall back to
`text` when it is `null`.
llm_error:
type: string
nullable: true
enum:
- timeout
- error
description: >-
Set when the rewrite failed. `timeout` means the rewrite passed its
5-second internal deadline. `null` on success.
audio_duration_ms:
type: number
description: Duration of the submitted audio in milliseconds.
session_id:
type: string
format: uuid
description: >-
Server-generated request identifier. Include it when reporting
problems.
request_time_ms:
type: number
format: float
description: Total server-side processing time in milliseconds.
sync_time_ms:
type: number
format: float
description: The transcription portion of `request_time_ms`, in milliseconds.
ErrorResponse:
type: object
properties:
error:
type: string
description: Human-readable error description.
error_code:
type: string
description: >-
Machine-readable error code, the snake_cased problem-details title
from the server.
enum:
- bad_request
- bad_audio
- audio_too_large
- capacity_exceeded
- inference_timeout
DetailErrorResponse:
type: object
description: >-
Shape used by errors relayed from upstream services, including an
invalid API key (`404`) and an unsupported audio format (`415`).
properties:
status:
type: integer
title:
type: string
detail:
type: string
description: Human-readable error description.
Word:
type: object
required:
- text
- confidence
properties:
text:
type: string
confidence:
type: number
format: float
securitySchemes:
ApiKey:
type: apiKey
in: header
name: Authorization
description: >-
Your AssemblyAI API key, sent as the raw key with no `Bearer` prefix. An
invalid key returns `404`, not `401`.
````