> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# AssemblyAI

> Call and log AssemblyAI speech-to-text models through the Respan gateway with full observability.

[AssemblyAI](https://www.assemblyai.com/) is an applied AI company offering models for audio transcription, content moderation, summarization, topic detection, and more. Route AssemblyAI calls through the Respan gateway to get full observability over every transcription request.

#### Set up Respan

Create an account at [platform.respan.ai](https://platform.respan.ai) and grab an [API key](https://platform.respan.ai/platform/gateway/api-keys). For gateway, also add [credits](https://platform.respan.ai/platform/gateway/credits) or a [provider key](https://platform.respan.ai/platform/gateway/api-keys?providers=1).

Run `npx @respan/cli setup` to set up with your coding agent.

#### Gateway

> **Note**
>
> AssemblyAI is a gateway-only integration. The endpoint is `https://api.respan.ai/api/assemblyai/`.

## Setup

#### Set environment variables

```bash
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
export ASSEMBLYAI_API_KEY="YOUR_ASSEMBLYAI_API_KEY"
```

#### Wrap the AssemblyAI client to point at Respan

```python
import os
import json
from base64 import b64encode
from assemblyai import Transcriber, Client, Settings, TranscriptStatus

BASE_URL = "https://api.respan.ai/api/assemblyai/"

class RespanAssemblyAIClient(Client):
    """AssemblyAI client wrapper that routes through the Respan gateway."""

    def __init__(self, respan_api_key: str, headers: dict):
        settings = Settings(api_key=respan_api_key, base_url=BASE_URL)
        super().__init__(settings=settings)
        self._http_client.headers.update(headers)

respan_params = {
    "metadata": {"paid_user": "true"},
    # other respan parameters...
}

respan_headers = {
    "X-Assemblyai-Api-Key": os.environ["ASSEMBLYAI_API_KEY"],
    "X-Data-Respan-Params": b64encode(json.dumps(respan_params).encode()).decode(),
}

client = RespanAssemblyAIClient(
    respan_api_key=os.environ["RESPAN_API_KEY"],
    headers=respan_headers,
)

transcriber = Transcriber(client=client)
transcript = transcriber.transcribe("https://assembly.ai/wildfires.mp3")

if transcript.status == TranscriptStatus.error:
    print(transcript.error)
else:
    print(transcript.text)
```

#### View your trace

Open the [Traces page](https://platform.respan.ai/platform/traces) to see transcription requests with audio, output, and timing.

## Respan params

Pass any [Respan params & metadata](/docs/documentation/features/gateway/respan-params) in the `respan_params` dict (base64-encoded into `X-Data-Respan-Params`).

| Parameter             | Description                                  |
| --------------------- | -------------------------------------------- |
| `customer_identifier` | Identifies the end user.                     |
| `thread_identifier`   | Groups related messages into a conversation. |
| `metadata`            | Custom key-value pairs.                      |