> ## 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.

# 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](https://en.wikipedia.org/wiki/REST) with [JSON-encoded](https://www.json.org/json-en.html) request bodies and responses, and is available at the following URL:

```plain title="Base URL" theme={null}
https://api.assemblyai.com
```

<Note>
  To use our EU server for Pre-recorded STT, replace `api.assemblyai.com` with
  `api.eu.assemblyai.com`. See [Cloud Endpoints and Data
  Residency](/pre-recorded-audio/select-the-region) for more information.
</Note>

### 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](https://www.assemblyai.com/app/api-keys).

```bash title="Authenticated request" theme={null}
curl https://api.assemblyai.com/v2/transcript \
  --header 'Authorization: <YOUR_API_KEY>'
```

<Info>
  **Your API key**

  The examples here contain a placeholder, `<YOUR_API_KEY>`, that you need to replace with your actual API key.
</Info>

### 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.         |
| 403           | Too many requests | Too many requests were sent to the API.       |
| 500, 503, 504 | Server error      | Something went wrong on AssemblyAI's end.     |

```json title="Response with error" theme={null}
{
  "error": "Authentication error, API token missing/invalid"
}
```

<Tip>
  **API status**

  To stay up-to-date with any known service disruptions, subscribe to updates on
  the [Status](https://status.assemblyai.com) page.
</Tip>

#### 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.

```json title="Failed transcription" theme={null}
{
    "status": "error",
    "error": "Download error to https://foo.bar, 403 Client Error: Forbidden for url: https://foo.bar",
    ...
}
```

Common reasons why a transcription may fail include:

* Audio data is corrupted or in an unsupported format. See [FAQ](/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).
* The file exceeds the 5.5 GB cap, contains no audio stream, returns an empty body, or — for uploaded files — was uploaded in a different region from the transcript request.
* [Automatic Language Detection](/pre-recorded-audio/language-detection) couldn't run on the file, or the detected language's confidence was below the configured `language_confidence_threshold`.

For the full list of error strings (request-time and processing-time) and recommended fixes, see [Troubleshoot Common Errors](/pre-recorded-audio/guides/common_errors_and_solutions).

In the rare event of a transcription failure due to a server error, you may resubmit the file for transcription. See [Implement Retry Server Error Logic](/pre-recorded-audio/guides/retry-server-error) for a worked example. If the problems persist after resubmitting, [let us know](mailto:support@assemblyai.com).

## Real-time STT

The Streaming Speech-to-Text API uses [WebSockets](https://en.wikipedia.org/wiki/WebSocket) for real-time audio transcription. See [Streaming API reference](/api-reference/streaming-api/universal-streaming) for full endpoint documentation.

```plain title="Base URL" theme={null}
wss://streaming.assemblyai.com
```

<Note>
  To use our EU server for Real-time STT, use `streaming.eu.assemblyai.com`. See
  [Streaming Endpoints and Data Zones](/streaming/endpoints-and-data-zones)
  for more information.
</Note>

Real-time 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.

```plain title="Base URL" theme={null}
https://llm-gateway.assemblyai.com
```

<Note>
  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](/llm-gateway/cloud-endpoints-and-data-residency) for more
  information.
</Note>

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.

<Info>
  **Increasing rate limits**

  If you want to increase the rate limit for your account, [contact
  us](mailto:support@assemblyai.com).
</Info>

## Versioning

When AssemblyAI makes backwards-incompatible changes to the API, we release a new version. For information on API updates, see [Changelog](https://www.assemblyai.com/changelog).

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