Transcribe a short audio file

Overview

Send an audio file in a single call, get a transcript back in milliseconds. No polling, no session management. The SDKs wrap the whole round trip in one method:

Python SDK
JavaScript SDK

import os

from assemblyai.sync.v1 import SyncTranscriber

transcriber = SyncTranscriber(api_key=os.environ["ASSEMBLYAI_API_KEY"])
result = transcriber.transcribe("./sample.wav")
print(result.text)

import { AssemblyAI } from "assemblyai";

const client = new AssemblyAI({ apiKey: process.env.ASSEMBLYAI_API_KEY });

const result = await client.sync.transcribe("./sample.wav");
console.log(result.text);

The Sync API uses our flagship Universal-3.5 Pro model and accepts audio from 80 milliseconds up to 120 seconds. It transcribes with state-of-the-art accuracy in 19 languages. Not using an SDK? The same flow works over plain HTTP — see Using the HTTP API directly.

When to use Sync STTSync STT is ideal for pre-recorded audio clips under 2 minutes where you need an immediate response without polling — for example, voice message transcription, short call recordings, or voice agent pipelines that handle turn detection externally and submit completed utterances for transcription. For audio longer than 120 seconds, use Pre-recorded STT. For live microphone audio, use Real-time STT.

Before you begin

To complete this guide, you need:

An API key — browse to API Keys in your dashboard and copy your key. Every example below reads it from an environment variable, so set it once:
export ASSEMBLYAI_API_KEY=<your-key>
An audio file in WAV format (or raw PCM S16LE), between 80 milliseconds and 120 seconds long.
Python 3.8+ for the Python SDK, or Node.js 18+ for the JavaScript SDK. The HTTP examples at the bottom of this page need Python 3.8+, Node.js 18+, or cURL.

Transcribe your first file

Step 1: Install the SDK

Python SDK
JavaScript SDK

pip install -U assemblyai

npm install assemblyai

Step 2: Run your first transcription

Save this as transcribe.py (Python) or transcribe.mjs (JavaScript), next to a sample.wav file:

Python SDK
JavaScript SDK

import os

from assemblyai.sync.v1 import SyncTranscriber

transcriber = SyncTranscriber(api_key=os.environ["ASSEMBLYAI_API_KEY"])
result = transcriber.transcribe("./sample.wav")
print(result.text)

import { AssemblyAI } from "assemblyai";

const client = new AssemblyAI({ apiKey: process.env.ASSEMBLYAI_API_KEY });

const result = await client.sync.transcribe("./sample.wav");
console.log(result.text);

Then run it — python transcribe.py or node transcribe.mjs. You’ll see the transcript printed:

Hi, I'm calling about my Best Buy order...

transcribe() accepts a local file path or raw audio bytes — an open binary file object in Python, or a Uint8Array, Blob, or readable stream in JavaScript — but not a URL. The Sync API has no URL ingestion; for remote files, download them first or use Pre-recorded STT.

Customize your request

The call above works with no extra configuration. Pass a config to change how the audio is transcribed — in Python a SyncTranscriptionConfig, either as the transcriber’s default (SyncTranscriber(config=...)) or per call (transcribe(data, config=...)); in JavaScript, a plain object as the second argument to transcribe().

Select a model

model selects the sync speech model and defaults to universal-3-5-pro. Set it explicitly to pin the model:

Python SDK
JavaScript SDK

from assemblyai.sync.v1 import SyncTranscriptionConfig

config = SyncTranscriptionConfig(model="universal-3-5-pro")
result = transcriber.transcribe("./sample.wav", config=config)

const result = await client.sync.transcribe("./sample.wav", {
  model: "universal-3-5-pro",
});

Choose a language

Pass language_codes as a list of ISO 639-1 codes — one code for monolingual audio, several for multilingual audio:

Python SDK
JavaScript SDK

from assemblyai.sync.v1 import SyncTranscriptionConfig

config = SyncTranscriptionConfig(language_codes=["es"])
result = transcriber.transcribe("./sample.wav", config=config)

const result = await client.sync.transcribe("./sample.wav", {
  language_codes: ["es"],
});

Get word timestamps

Per-word timings are opt-in. Set timestamps=True to compute start/end for every word, at a small latency cost. Without it, words carry text and confidence only:

Python SDK
JavaScript SDK

from assemblyai.sync.v1 import SyncTranscriptionConfig

config = SyncTranscriptionConfig(timestamps=True)
result = transcriber.transcribe("./sample.wav", config=config)

for word in result.words:
    print(word.text, word.start, word.end)  # milliseconds

const result = await client.sync.transcribe("./sample.wav", {
  timestamps: true,
});

for (const word of result.words) {
  console.log(word.text, word.start, word.end); // milliseconds
}

Transcribe raw PCM audio

WAV files carry their sample rate and channel count in the file header. Raw PCM (S16LE little-endian) doesn’t, so set sample_rate and channels on the config — both are required, and setting either one routes the audio as raw PCM:

Python SDK
JavaScript SDK

from assemblyai.sync.v1 import SyncTranscriptionConfig

config = SyncTranscriptionConfig(sample_rate=16000, channels=1)

with open("./sample.pcm", "rb") as f:
    result = transcriber.transcribe(f.read(), config=config)

print(result.text)

import { readFileSync } from "fs";

const audio = readFileSync("./sample.pcm");

const result = await client.sync.transcribe(audio, {
  sample_rate: 16000,
  channels: 1,
});

console.log(result.text);

Complete example

Here’s the complete, runnable script — the call above plus options and error handling:

Python SDK
JavaScript SDK

import os

from assemblyai.sync.v1 import (
    SyncTranscriber,
    SyncTranscriptError,
    SyncTranscriptionConfig,
)

config = SyncTranscriptionConfig(
    model="universal-3-5-pro",
    language_codes=["en"],
    timestamps=True,
)

with SyncTranscriber(api_key=os.environ["ASSEMBLYAI_API_KEY"]) as transcriber:
    try:
        result = transcriber.transcribe("./sample.wav", config=config)
    except SyncTranscriptError as error:
        # error_code is machine-readable (bad_audio, audio_too_large,
        # capacity_exceeded, inference_timeout, ...); retry_after is set on
        # 429/503 responses. See /sync-stt/error-handling
        raise RuntimeError(
            f"Transcription failed ({error.status_code}/{error.error_code}): {error}"
        ) from error

    # Record session_id for every request, not just errors — it's the first
    # thing support@assemblyai.com asks for.
    print(f"session_id: {result.session_id}")
    print(f"\nFull Transcript:\n\n{result.text}")

    for word in result.words:
        print(f"{word.text} ({word.confidence:.2f}) {word.start}-{word.end}ms")

import { AssemblyAI, SyncTranscriptError } from "assemblyai";

const client = new AssemblyAI({ apiKey: process.env.ASSEMBLYAI_API_KEY });

try {
  const result = await client.sync.transcribe("./sample.wav", {
    model: "universal-3-5-pro",
    language_codes: ["en"],
    timestamps: true,
  });

  // Record session_id for every request, not just errors — it's the first
  // thing support@assemblyai.com asks for.
  console.log(`session_id: ${result.session_id}`);
  console.log(`\nFull Transcript:\n\n${result.text}`);

  for (const word of result.words) {
    console.log(
      `${word.text} (${word.confidence.toFixed(2)}) ${word.start}-${word.end}ms`
    );
  }
} catch (error) {
  if (error instanceof SyncTranscriptError) {
    // errorCode is machine-readable (bad_audio, audio_too_large,
    // capacity_exceeded, inference_timeout, ...); retryAfter is set on
    // 429/503 responses. See /sync-stt/error-handling
    throw new Error(
      `Transcription failed (${error.status}/${error.errorCode}): ${error.message}`
    );
  }
  throw error;
}

Calling the Sync API repeatedly? warm() opens the connection ahead of time so your next transcribe() doesn’t pay the DNS, TCP, and TLS handshake on the critical path. See Connection pre-warming.

What you get back

transcribe() returns a SyncTranscriptResponse with the transcript and word-level details:

Attribute	Description
`result.text`	Full transcript of the audio.
`result.words`	Per-word `text` and `confidence`, plus `start`/`end` timestamps (in milliseconds) when the request sets `timestamps=True`. Otherwise `start`/`end` are `None`.
`result.confidence`	Overall transcript confidence score (0–1).
`result.audio_duration_ms`	Duration of the submitted audio in milliseconds.
`result.session_id`	Server-generated UUID. Include this when contacting support.
`result.request_time_ms`	End-to-end server-side processing time for the request, in milliseconds.

Failed requests raise SyncTranscriptError, which carries the HTTP status, a machine-readable error code (for example bad_audio, audio_too_large, capacity_exceeded, inference_timeout), and a retry-after value in seconds for 429/503 responses — named status_code/error_code/retry_after in the Python SDK and status/errorCode/retryAfter in the JavaScript SDK. See Error handling for status codes and retry guidance.

Using the HTTP API directly

If you prefer to call the Sync API over HTTP without an SDK, post the audio to POST https://sync.assemblyai.com/transcribe and read the transcript out of the JSON response. The Sync API accepts multipart/form-data with an audio part. For WAV files, set the part’s Content-Type to audio/wav. Authenticate with your key in the Authorization header (no Bearer prefix), and send the X-AAI-Model: universal-3-5-pro header — it is required on every request.

cURL
Python
JavaScript

Replace <YOUR_API_KEY> in the request header:

curl -X POST https://sync.assemblyai.com/transcribe \
  -H 'Authorization: <YOUR_API_KEY>' \
  -H 'X-AAI-Model: universal-3-5-pro' \
  -F 'audio=@sample.wav;type=audio/wav'

The response JSON is printed to stdout. Pipe to jq to extract fields:

curl -X POST https://sync.assemblyai.com/transcribe \
  -H 'Authorization: <YOUR_API_KEY>' \
  -H 'X-AAI-Model: universal-3-5-pro' \
  -F 'audio=@sample.wav;type=audio/wav' \
  | jq '.text'

Install the requests library if you haven’t already:

pip install requests

Send the audio file and parse the response:

import requests

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

response = requests.post(
    "https://sync.assemblyai.com/transcribe",
    headers={
        "Authorization": "<YOUR_API_KEY>",
        "X-AAI-Model": "universal-3-5-pro",
    },
    files={
        "audio": ("sample.wav", audio, "audio/wav"),
    },
    timeout=60,
)
response.raise_for_status()
result = response.json()
print(result["text"])
print(result["session_id"])

import { readFileSync } from "fs";

const audio = readFileSync("sample.wav");
const form = new FormData();
form.append("audio", new Blob([audio], { type: "audio/wav" }), "sample.wav");

const response = await fetch("https://sync.assemblyai.com/transcribe", {
  method: "POST",
  headers: {
    Authorization: "<YOUR_API_KEY>",
    "X-AAI-Model": "universal-3-5-pro",
  },
  body: form,
});

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

const result = await response.json();
console.log(result.text);
console.log(result.session_id);

Response shape

A successful request returns a JSON object with the transcript and word-level details:

{
  "text": "Hi, I'm calling about my Best Buy order...",
  "words": [
    { "text": "Hi",  "confidence": 0.91 },
    { "text": "I'm", "confidence": 0.88 }
  ],
  "confidence": 0.87,
  "audio_duration_ms": 101567,
  "session_id": "eb92c4ff-4bbb-429f-9b99-7279d7fe738f",
  "request_time_ms": 243.7
}

Field	Description
`text`	Full transcript of the audio.
`words`	Per-word `confidence`, plus `start`/`end` timestamps (in milliseconds) when the request enables word timestamps.
`confidence`	Overall transcript confidence score (0–1).
`audio_duration_ms`	Duration of the submitted audio in milliseconds.
`session_id`	Server-generated UUID. Include this when contacting support.
`request_time_ms`	End-to-end server-side processing time for the request, in milliseconds.

Sending raw PCM audio

When your audio is raw PCM (S16LE little-endian), set the audio part Content-Type to audio/pcm and include sample_rate and channels in the config part:

cURL
Python
JavaScript

curl -X POST https://sync.assemblyai.com/transcribe \
  -H 'Authorization: <YOUR_API_KEY>' \
  -H 'X-AAI-Model: universal-3-5-pro' \
  -F 'audio=@sample.pcm;type=audio/pcm' \
  -F 'config={"sample_rate":16000,"channels":1};type=application/json'

import json
import requests

with open("sample.pcm", "rb") as f:
    audio = f.read()

response = requests.post(
    "https://sync.assemblyai.com/transcribe",
    headers={
        "Authorization": "<YOUR_API_KEY>",
        "X-AAI-Model": "universal-3-5-pro",
    },
    files={
        "audio": ("sample.pcm", audio, "audio/pcm"),
        "config": (
            None,
            json.dumps({"sample_rate": 16000, "channels": 1}),
            "application/json",
        ),
    },
    timeout=60,
)
response.raise_for_status()
print(response.json()["text"])

import { readFileSync } from "fs";

const audio = readFileSync("sample.pcm");
const form = new FormData();
form.append("audio", new Blob([audio], { type: "audio/pcm" }), "sample.pcm");
form.append(
  "config",
  new Blob(
    [JSON.stringify({ sample_rate: 16000, channels: 1 })],
    { type: "application/json" }
  )
);

const response = await fetch("https://sync.assemblyai.com/transcribe", {
  method: "POST",
  headers: {
    Authorization: "<YOUR_API_KEY>",
    "X-AAI-Model": "universal-3-5-pro",
  },
  body: form,
});

const result = await response.json();
console.log(result.text);

Next steps

Prompting and keyterms — improve accuracy with contextual prompts and keyterm biasing
Conversation context — pass prior dialogue for multi-turn continuity
Language selection — transcribe in any of the 19 supported languages
Word timestamps — get per-word start/end timings
Audio requirements — duration, size, and format constraints
Connection pre-warming — cut the handshake off the critical path
Error handling — status codes and retry guidance
Cloud endpoints & data residency — use the EU endpoint for data residency
API reference — full endpoint documentation

Need help?

If you get stuck, contact our support team at support@assemblyai.com or create a support ticket. Include the session_id from the response to help us look up your request.

Getting started

Features

API reference

Advanced

Transcribe a short audio file

Overview

Before you begin

Transcribe your first file

Step 1: Install the SDK

Step 2: Run your first transcription

Customize your request

Select a model

Choose a language

Get word timestamps

Transcribe raw PCM audio

Complete example

What you get back

Using the HTTP API directly

Response shape

Sending raw PCM audio

Next steps

Need help?

​Overview

​Before you begin

​Transcribe your first file

​Step 1: Install the SDK

​Step 2: Run your first transcription

​Customize your request

​Select a model

​Choose a language

​Get word timestamps

​Transcribe raw PCM audio

​Complete example

​What you get back

​Using the HTTP API directly

​Response shape

​Sending raw PCM audio

​Next steps

​Need help?

Overview

Before you begin

Transcribe your first file

Step 1: Install the SDK

Step 2: Run your first transcription

Customize your request

Select a model

Choose a language

Get word timestamps

Transcribe raw PCM audio

Complete example

What you get back

Using the HTTP API directly

Response shape

Sending raw PCM audio

Next steps

Need help?