Overview

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:

1
https://api.assemblyai.com

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 https://api.assemblyai.com/v2/transcript \
>
  --header 'Authorization: <YOUR_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:

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

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.

1
{
2
    "status": "error",
3
    "error": "Download error to https://foo.bar, 403 Client Error: Forbidden for url: https://foo.bar",
4
    ...
5
}

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.

1
wss://streaming.assemblyai.com

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.

1
https://llm-gateway.assemblyai.com

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:

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

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.