For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see For full documentation content, see For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at

Overview

For the complete documentation index, see llms.txt

Quick API Reference

Base URLs:

• Pre-recorded STT: (EU:)
• Streaming STT: wss://streaming.assemblyai.com (EU: wss://streaming.eu.assemblyai.com)
• LLM Gateway: (EU:)

Authentication: Pass your API key in the Authorization header: Authorization: YOUR_API_KEY

Core endpoints:

• POST /v2/upload — Upload a local file and get a temporary URL
• POST /v2/transcript — Submit audio for transcription (returns transcript ID)
• GET /v2/transcript/{id} — Get transcript (poll until status is completed or error)
• GET /v2/transcript/{id}/sentences — Get transcript split into sentences
• GET /v2/transcript/{id}/paragraphs — Get transcript split into paragraphs
• GET /v2/transcript/{id}/srt or /vtt — Export as SRT/VTT subtitles
• GET /v2/transcript/{id}/redacted-audio — Get PII-redacted audio
• GET /v2/transcript/{id}/word-search?words=foo,bar — Search for words
• GET /v2/transcript — List recent transcripts
• DELETE /v2/transcript/{id} — Delete a transcript

LLM Gateway endpoints:

• POST /v1/chat/completions — Chat completions with audio context (OpenAI-compatible)
• POST /v1/speech-understanding — Speech understanding with structured output

Streaming: Connect via WebSocket to wss://streaming.assemblyai.com/v3/ws with your API key as a query parameter or in the initial message.

Full OpenAPI spec: Available at openapi.yaml and openapi.json.

This page describes how to perform common operations with the AssemblyAI APIs. Each endpoint is documented individually and grouped by the resource it interacts with.

Pre-recorded STT

The Pre-recorded Speech-to-Text API uses REST with JSON-encoded request bodies and responses, and is available at the following URL:

To use our EU server for Pre-recorded STT, replace api.assemblyai.com with api.eu.assemblyai.com. See Cloud Endpoints and Data Residency for more information.

Authentication

To make authorized calls to the REST API, your app must provide an authorization header with an API key. You can find your API key in the AssemblyAI dashboard.

curl  \
  --header 'Authorization: <YOUR_API_KEY>'

The examples here contain a placeholder, ``, that you need to replace with your actual API key.

Errors

The AssemblyAI API uses HTTP response codes to indicate whether a request was successful.

The response codes generally fall into the following ranges:

• 2xx indicates the request was successful.
• 4xx indicates the request may have omitted a required parameter, or have invalid information.
• 5xx indicates an error on AssemblyAI's end.

Below is a summary of the HTTP response codes you may encounter:

Code	Status	Description
200	OK	Request was successful.
400	Bad request	The request failed due to an invalid request.
401	Unauthorized	Missing or invalid API key.
404	Not found	The requested resource doesn't exist.
429	Too many requests	Too many requests were sent to the API.
500, 503, 504	Server error	Something went wrong on AssemblyAI's end.

{
  "error": "Authentication error, API token missing/invalid"
}

To stay up-to-date with any known service disruptions, subscribe to updates on the Status page.

Failed transcriptions

Transcriptions may fail due to errors while processing the audio data.

When you query a transcription that has failed, the response will have a 200 code, along with status set to error and an error property with more details.

{
    "status": "error",
    "error": "Download error to  403 Client Error: Forbidden for url: ",
    ...
}

Common reasons why a transcription may fail include:

• Audio data is corrupted or in an unsupported format. See FAQ for supported formats.
• Audio URL is a webpage rather than a file.
• Audio URL isn't accessible from AssemblyAI's servers.
• Audio duration is too short (less than 160ms).

In the rare event of a transcription failure due to a server error, you may resubmit the file for transcription. If the problems persist after resubmitting, let us know.

Streaming STT

The Streaming Speech-to-Text API uses WebSockets for real-time audio transcription. See Streaming API reference for full endpoint documentation.

wss://streaming.assemblyai.com

To use our EU server for Streaming STT, use streaming.eu.assemblyai.com. See Streaming Endpoints and Data Zones for more information.

Streaming STT uses the same API key for authentication as Pre-recorded STT. Pass the API key as a query parameter or in the initial WebSocket message.

LLM Gateway

The LLM Gateway API provides a unified interface for interacting with multiple LLM providers through a single endpoint.

To use our EU server for LLM Gateway, replace llm-gateway.assemblyai.com with llm-gateway.eu.assemblyai.com. See Cloud Endpoints and Data Residency for more information.

LLM Gateway uses the same API key for authentication as Pre-recorded STT. Pass your API key in the Authorization header.

Rate limits

To ensure the LLM Gateway API remains available for all users, you can only make a limited number of requests within a 60-second time window. These rate limits are specific to each LLM Gateway model.

If you exceed the limit, the API will respond with a 429 status code.

To see your remaining quota, check the following response headers:

Header	Description
X-RateLimit-Limit	Maximum number of allowed requests in a 60 second window.
X-RateLimit-Remaining	Number of remaining requests in the current time window.
X-RateLimit-Reset	Number of seconds until the remaining requests resets to the value of X-RateLimit-Limit.
X-RateLimit-Model	The model the rate limit applies to. Same as "model" param in the request.
X-RateLimit-Service	Denotes the service used, LLM Gateway or Speech Understanding

If the response doesn't include X-RateLimit headers, the endpoint doesn't have rate limits.

If you want to increase the rate limit for your account, contact us.

Versioning

When AssemblyAI makes backwards-incompatible changes to the API, we release a new version. For information on API updates, see Changelog.

Endpoints are versioned using a path prefix, such as /v2.