> ## 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 recorded audio ## OpenAPI ````yaml specs/dictation.yaml POST /v1/transcribe openapi: 3.1.0 info: title: AssemblyAI Dictation API description: >- Short-form dictation that returns send-ready cleaned-up text together with the verbatim transcript, 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: post: summary: Transcribe recorded audio description: | Send a complete recording and receive text ready to send, together with the verbatim transcript. Audio must be between 80 ms and 20 minutes, and at most 256 MB. This endpoint takes audio you already hold in full. The server reads the whole body before it starts transcribing, so the `config` part can come before or after `audio`, and can be left out to use the defaults. Besides WAV and raw PCM, it accepts compressed audio: AAC, MP3, M4A, Ogg/Opus, FLAC, and WebM. For audio that is still being recorded, use [`/v1/transcribe/live`](/api-reference/dictation-api/transcribe-live) instead. It uploads while the user speaks and accepts up to 120 seconds of WAV or raw PCM. The SDKs use `/v1/transcribe/live`, so this endpoint is called over HTTP. This endpoint is also served at `/transcribe`, without the version prefix. operationId: transcribeDictationRecording requestBody: required: true content: multipart/form-data: schema: type: object required: - audio properties: config: type: object additionalProperties: false description: >- Transcription and rewrite configuration. Optional; when omitted, the audio is transcribed with defaults, including the default rewrite. Only the fields below are accepted. An unknown field is rejected with a `400`. properties: sample_rate: type: integer description: >- Source sample rate in Hz, for example `16000`. Required when `audio` is `audio/pcm`. Not needed for WAV or compressed formats, which carry it in the file. channels: type: integer description: >- Number of audio channels. Required when `audio` is `audio/pcm`. Not needed for WAV or compressed formats. language_codes: type: array items: type: string enum: - en - es - de - fr - it - pt - tr - nl - sv - 'no' - da - fi - hi - vi - ar - he - ja - ur - zh - ko - ca - gl - ru - ro - et - fa - yue - af - mr - zu - xh - nn description: >- Language or languages of the audio, as ISO language codes. A code outside this set is rejected with a `400`. When omitted, no language steering is applied. 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 nullable: true description: >- Plain-English description of the shape you want the text in, 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 filler, resolves self-corrections, and applies punctuation and capitalization. audio: type: string format: binary description: >- Audio bytes, between 80 ms and 20 minutes and at most 256 MB. Set the part's Content-Type to the format: `audio/wav`, `audio/pcm` (raw 16-bit PCM), `audio/aac`, `audio/mpeg` (MP3), `audio/mp4` (M4A), `audio/ogg` (Ogg/Opus), `audio/flac`, or `audio/webm`. encoding: config: contentType: application/json audio: contentType: >- audio/wav, audio/pcm, audio/aac, audio/mpeg, audio/mp4, audio/ogg, audio/flac, audio/webm 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' '400': description: >- A malformed request body, or a Dictation-specific `config` field that fails validation, uses the `error`/`error_code` shape: a missing or empty `audio` part, an `audio` part over 256 MB, or `config` that is not valid JSON. Audio shorter than 80 ms, audio that cannot be decoded, and a transcription `config` field that fails validation, including an unknown field, use the `status`/`title`/`detail` shape instead. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorResponse' - $ref: '#/components/schemas/DetailErrorResponse' '401': description: Missing `Authorization` header, or an invalid API key. content: application/json: schema: $ref: '#/components/schemas/DetailErrorResponse' '413': description: 'The audio is longer than 20 minutes (`title: "Audio Too Large"`).' content: application/json: schema: $ref: '#/components/schemas/DetailErrorResponse' '415': description: The `audio` part's Content-Type is not a supported format. content: application/json: schema: $ref: '#/components/schemas/DetailErrorResponse' '429': description: Rate limited. Back off and retry. content: application/json: schema: $ref: '#/components/schemas/DetailErrorResponse' '502': description: >- Transcription upstream unavailable (`error_code: "upstream_error"`). Retry once, then surface an error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Server at capacity. Back off and retry. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorResponse' - $ref: '#/components/schemas/DetailErrorResponse' '504': description: Transcription timed out. Retry once, then surface an error. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorResponse' - $ref: '#/components/schemas/DetailErrorResponse' x-codeSamples: - lang: bash label: cURL source: | curl -X POST https://dictation.assemblyai.com/v1/transcribe \ -H 'Authorization: ' \ -F 'audio=@recording.mp3;type=audio/mpeg' - lang: python label: Python source: | import requests with open("recording.mp3", "rb") as f: audio = f.read() response = requests.post( "https://dictation.assemblyai.com/v1/transcribe", headers={"Authorization": ""}, files={ "audio": ("recording.mp3", audio, "audio/mpeg"), # Optional; omit for the defaults. "config": (None, '{"language_codes": ["en"]}', "application/json"), }, 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("recording.mp3"); const form = new FormData(); form.append("audio", new Blob([audio], { type: "audio/mpeg" }), "recording.mp3"); const response = await fetch( "https://dictation.assemblyai.com/v1/transcribe", { 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 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. auth_time_ms: type: number format: float description: >- Time in milliseconds spent authenticating the request, included in `request_time_ms`. 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, such as `bad_request`, `audio_too_large`, `capacity_exceeded`, `upstream_error`, or `upstream_timeout`. DetailErrorResponse: type: object description: >- The shape used by auth failures (`401`), rate limiting (`429`), and errors from the transcription step, including transcription `config` validation failures (`400`) and unsupported audio formats (`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. A missing header or an invalid key returns `401`. ````