cURL
curl -X POST https://dictation.assemblyai.com/v1/transcribe \
-H 'Authorization: <YOUR_API_KEY>' \
-F 'audio=@recording.mp3;type=audio/mpeg'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"),
# 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
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: "<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); // default cleanup rewrite
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://dictation.assemblyai.com/v1/transcribe",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio\"; filename=\"example-file\"\r\nContent-Type: audio/wav\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"config\"\r\nContent-Type: application/json\r\n\r\n{\r\n \"sample_rate\": 123,\r\n \"channels\": 123,\r\n \"language_codes\": [],\r\n \"stt_prompt\": \"<string>\",\r\n \"keyterms_prompt\": [\r\n \"<string>\"\r\n ],\r\n \"llm_instruction\": \"<string>\",\r\n \"rewrite_mode\": \"fast\",\r\n \"llm\": {\r\n \"messages\": [\r\n {}\r\n ],\r\n \"prompt\": \"<string>\",\r\n \"temperature\": 0,\r\n \"top_p\": 123,\r\n \"top_k\": 123,\r\n \"max_tokens\": 123,\r\n \"max_completion_tokens\": 123,\r\n \"response_format\": {},\r\n \"reasoning_effort\": \"<string>\",\r\n \"zero_data_retention\": true,\r\n \"aai_prompt\": \"<string>\",\r\n \"prompt_replacements\": {}\r\n }\r\n}\r\n-----011000010111000001101001--",
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: multipart/form-data; boundary=---011000010111000001101001"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://dictation.assemblyai.com/v1/transcribe"
payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio\"; filename=\"example-file\"\r\nContent-Type: audio/wav\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"config\"\r\nContent-Type: application/json\r\n\r\n{\r\n \"sample_rate\": 123,\r\n \"channels\": 123,\r\n \"language_codes\": [],\r\n \"stt_prompt\": \"<string>\",\r\n \"keyterms_prompt\": [\r\n \"<string>\"\r\n ],\r\n \"llm_instruction\": \"<string>\",\r\n \"rewrite_mode\": \"fast\",\r\n \"llm\": {\r\n \"messages\": [\r\n {}\r\n ],\r\n \"prompt\": \"<string>\",\r\n \"temperature\": 0,\r\n \"top_p\": 123,\r\n \"top_k\": 123,\r\n \"max_tokens\": 123,\r\n \"max_completion_tokens\": 123,\r\n \"response_format\": {},\r\n \"reasoning_effort\": \"<string>\",\r\n \"zero_data_retention\": true,\r\n \"aai_prompt\": \"<string>\",\r\n \"prompt_replacements\": {}\r\n }\r\n}\r\n-----011000010111000001101001--")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://dictation.assemblyai.com/v1/transcribe")
.header("Authorization", "<api-key>")
.header("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")
.body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio\"; filename=\"example-file\"\r\nContent-Type: audio/wav\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"config\"\r\nContent-Type: application/json\r\n\r\n{\r\n \"sample_rate\": 123,\r\n \"channels\": 123,\r\n \"language_codes\": [],\r\n \"stt_prompt\": \"<string>\",\r\n \"keyterms_prompt\": [\r\n \"<string>\"\r\n ],\r\n \"llm_instruction\": \"<string>\",\r\n \"rewrite_mode\": \"fast\",\r\n \"llm\": {\r\n \"messages\": [\r\n {}\r\n ],\r\n \"prompt\": \"<string>\",\r\n \"temperature\": 0,\r\n \"top_p\": 123,\r\n \"top_k\": 123,\r\n \"max_tokens\": 123,\r\n \"max_completion_tokens\": 123,\r\n \"response_format\": {},\r\n \"reasoning_effort\": \"<string>\",\r\n \"zero_data_retention\": true,\r\n \"aai_prompt\": \"<string>\",\r\n \"prompt_replacements\": {}\r\n }\r\n}\r\n-----011000010111000001101001--")
.asString();require 'uri'
require 'net/http'
url = URI("https://dictation.assemblyai.com/v1/transcribe")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'multipart/form-data; boundary=---011000010111000001101001'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio\"; filename=\"example-file\"\r\nContent-Type: audio/wav\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"config\"\r\nContent-Type: application/json\r\n\r\n{\r\n \"sample_rate\": 123,\r\n \"channels\": 123,\r\n \"language_codes\": [],\r\n \"stt_prompt\": \"<string>\",\r\n \"keyterms_prompt\": [\r\n \"<string>\"\r\n ],\r\n \"llm_instruction\": \"<string>\",\r\n \"rewrite_mode\": \"fast\",\r\n \"llm\": {\r\n \"messages\": [\r\n {}\r\n ],\r\n \"prompt\": \"<string>\",\r\n \"temperature\": 0,\r\n \"top_p\": 123,\r\n \"top_k\": 123,\r\n \"max_tokens\": 123,\r\n \"max_completion_tokens\": 123,\r\n \"response_format\": {},\r\n \"reasoning_effort\": \"<string>\",\r\n \"zero_data_retention\": true,\r\n \"aai_prompt\": \"<string>\",\r\n \"prompt_replacements\": {}\r\n }\r\n}\r\n-----011000010111000001101001--"
response = http.request(request)
puts response.read_body{
"text": "<string>",
"words": [
{
"text": "<string>",
"confidence": 123
}
],
"confidence": 123,
"audio_duration_ms": 123,
"session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"llm_response": "<string>",
"llm_error": "timeout",
"request_time_ms": 123,
"auth_time_ms": 123,
"sync_time_ms": 123
}{
"error": "<string>",
"error_code": "<string>"
}{
"status": 123,
"title": "<string>",
"detail": "<string>"
}{
"status": 123,
"title": "<string>",
"detail": "<string>"
}{
"status": 123,
"title": "<string>",
"detail": "<string>"
}{
"status": 123,
"title": "<string>",
"detail": "<string>"
}{
"error": "<string>",
"error_code": "<string>"
}{
"error": "<string>",
"error_code": "<string>"
}{
"error": "<string>",
"error_code": "<string>"
}API reference
Transcribe recorded audio
POST
/
v1
/
transcribe
cURL
curl -X POST https://dictation.assemblyai.com/v1/transcribe \
-H 'Authorization: <YOUR_API_KEY>' \
-F 'audio=@recording.mp3;type=audio/mpeg'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"),
# 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
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: "<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); // default cleanup rewrite
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://dictation.assemblyai.com/v1/transcribe",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio\"; filename=\"example-file\"\r\nContent-Type: audio/wav\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"config\"\r\nContent-Type: application/json\r\n\r\n{\r\n \"sample_rate\": 123,\r\n \"channels\": 123,\r\n \"language_codes\": [],\r\n \"stt_prompt\": \"<string>\",\r\n \"keyterms_prompt\": [\r\n \"<string>\"\r\n ],\r\n \"llm_instruction\": \"<string>\",\r\n \"rewrite_mode\": \"fast\",\r\n \"llm\": {\r\n \"messages\": [\r\n {}\r\n ],\r\n \"prompt\": \"<string>\",\r\n \"temperature\": 0,\r\n \"top_p\": 123,\r\n \"top_k\": 123,\r\n \"max_tokens\": 123,\r\n \"max_completion_tokens\": 123,\r\n \"response_format\": {},\r\n \"reasoning_effort\": \"<string>\",\r\n \"zero_data_retention\": true,\r\n \"aai_prompt\": \"<string>\",\r\n \"prompt_replacements\": {}\r\n }\r\n}\r\n-----011000010111000001101001--",
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: multipart/form-data; boundary=---011000010111000001101001"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://dictation.assemblyai.com/v1/transcribe"
payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio\"; filename=\"example-file\"\r\nContent-Type: audio/wav\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"config\"\r\nContent-Type: application/json\r\n\r\n{\r\n \"sample_rate\": 123,\r\n \"channels\": 123,\r\n \"language_codes\": [],\r\n \"stt_prompt\": \"<string>\",\r\n \"keyterms_prompt\": [\r\n \"<string>\"\r\n ],\r\n \"llm_instruction\": \"<string>\",\r\n \"rewrite_mode\": \"fast\",\r\n \"llm\": {\r\n \"messages\": [\r\n {}\r\n ],\r\n \"prompt\": \"<string>\",\r\n \"temperature\": 0,\r\n \"top_p\": 123,\r\n \"top_k\": 123,\r\n \"max_tokens\": 123,\r\n \"max_completion_tokens\": 123,\r\n \"response_format\": {},\r\n \"reasoning_effort\": \"<string>\",\r\n \"zero_data_retention\": true,\r\n \"aai_prompt\": \"<string>\",\r\n \"prompt_replacements\": {}\r\n }\r\n}\r\n-----011000010111000001101001--")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://dictation.assemblyai.com/v1/transcribe")
.header("Authorization", "<api-key>")
.header("Content-Type", "multipart/form-data; boundary=---011000010111000001101001")
.body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio\"; filename=\"example-file\"\r\nContent-Type: audio/wav\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"config\"\r\nContent-Type: application/json\r\n\r\n{\r\n \"sample_rate\": 123,\r\n \"channels\": 123,\r\n \"language_codes\": [],\r\n \"stt_prompt\": \"<string>\",\r\n \"keyterms_prompt\": [\r\n \"<string>\"\r\n ],\r\n \"llm_instruction\": \"<string>\",\r\n \"rewrite_mode\": \"fast\",\r\n \"llm\": {\r\n \"messages\": [\r\n {}\r\n ],\r\n \"prompt\": \"<string>\",\r\n \"temperature\": 0,\r\n \"top_p\": 123,\r\n \"top_k\": 123,\r\n \"max_tokens\": 123,\r\n \"max_completion_tokens\": 123,\r\n \"response_format\": {},\r\n \"reasoning_effort\": \"<string>\",\r\n \"zero_data_retention\": true,\r\n \"aai_prompt\": \"<string>\",\r\n \"prompt_replacements\": {}\r\n }\r\n}\r\n-----011000010111000001101001--")
.asString();require 'uri'
require 'net/http'
url = URI("https://dictation.assemblyai.com/v1/transcribe")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'multipart/form-data; boundary=---011000010111000001101001'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"audio\"; filename=\"example-file\"\r\nContent-Type: audio/wav\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"config\"\r\nContent-Type: application/json\r\n\r\n{\r\n \"sample_rate\": 123,\r\n \"channels\": 123,\r\n \"language_codes\": [],\r\n \"stt_prompt\": \"<string>\",\r\n \"keyterms_prompt\": [\r\n \"<string>\"\r\n ],\r\n \"llm_instruction\": \"<string>\",\r\n \"rewrite_mode\": \"fast\",\r\n \"llm\": {\r\n \"messages\": [\r\n {}\r\n ],\r\n \"prompt\": \"<string>\",\r\n \"temperature\": 0,\r\n \"top_p\": 123,\r\n \"top_k\": 123,\r\n \"max_tokens\": 123,\r\n \"max_completion_tokens\": 123,\r\n \"response_format\": {},\r\n \"reasoning_effort\": \"<string>\",\r\n \"zero_data_retention\": true,\r\n \"aai_prompt\": \"<string>\",\r\n \"prompt_replacements\": {}\r\n }\r\n}\r\n-----011000010111000001101001--"
response = http.request(request)
puts response.read_body{
"text": "<string>",
"words": [
{
"text": "<string>",
"confidence": 123
}
],
"confidence": 123,
"audio_duration_ms": 123,
"session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"llm_response": "<string>",
"llm_error": "timeout",
"request_time_ms": 123,
"auth_time_ms": 123,
"sync_time_ms": 123
}{
"error": "<string>",
"error_code": "<string>"
}{
"status": 123,
"title": "<string>",
"detail": "<string>"
}{
"status": 123,
"title": "<string>",
"detail": "<string>"
}{
"status": 123,
"title": "<string>",
"detail": "<string>"
}{
"status": 123,
"title": "<string>",
"detail": "<string>"
}{
"error": "<string>",
"error_code": "<string>"
}{
"error": "<string>",
"error_code": "<string>"
}{
"error": "<string>",
"error_code": "<string>"
}Authorizations
Your AssemblyAI API key, sent as the raw key with no Bearer prefix. A missing header or an invalid key returns 401.
Body
multipart/form-data
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.
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.
Show child attributes
Show child attributes
Response
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.
The verbatim transcript. Never altered by the LLM.
Per-word transcript objects.
Show child attributes
Show child attributes
Overall transcription confidence (0–1).
Duration of the submitted audio in milliseconds.
Server-generated request identifier. Include it when reporting problems.
The rewritten text, or null when the rewrite failed. Fall back to text when it is null.
Set when the rewrite failed, and null on success. The transcription is still returned in text. timeout: the rewrite ran past its deadline. error: the model returned nothing usable, or an unexpected failure. truncated: the output hit max_tokens before finishing. prompt_not_found: your account has no saved prompt with the name in llm.aai_prompt. context_exceeded: the input is too long for the model's context window. unsupported_param: the model doesn't support a parameter that was sent. rate_limited: LLM Gateway returned 429. invalid_request: LLM Gateway rejected the request with any other 4xx. upstream_error: LLM Gateway returned a 5xx or another non-2xx error.
Available options:
timeout, error, truncated, prompt_not_found, context_exceeded, unsupported_param, rate_limited, invalid_request, upstream_error Total server-side processing time in milliseconds.
Time in milliseconds spent authenticating the request, included in request_time_ms.
The transcription portion of request_time_ms, in milliseconds.
Was this page helpful?