Skip to content

AssemblyAI Integration

Official AssemblyAI API Documentation

AssemblyAI provides AI models for speech-to-text transcription and understanding. Use KeyPool to call AssemblyAI with your team token and a stable base URL.

KeyPool Endpoint for AssemblyAI

To interact with AssemblyAI via KeyPool, configure your SDK with the following base URL:

{YOUR_KEYPOOL_BASE_URL}/v1/assemblyai

Authentication

Use your KeyPool team token as a bearer token when making requests to the KeyPool AssemblyAI endpoint.

Do not send a personal AssemblyAI API key when using KeyPool.

Free-plan limits

AssemblyAI's published free-plan limits are account-level:

Resource Free-plan limit
Pre-recorded transcription concurrency 5 parallel jobs
HTTP API requests 20,000 per 5 minutes
New real-time streaming sessions 5 per minute
API keys 2
Projects 2
Free credits $50 for Pre-recorded STT, Real-time STT, Voice Agent API, Speech Understanding, and Guardrails

Requests beyond the five-job pre-recorded limit are queued FIFO. The 20,000-request HTTP limit counts submissions and polling across all endpoints; prefer webhooks over tight polling. If the account balance goes below zero, AssemblyAI reduces the pre-recorded concurrency limit to 1.

These speech APIs do not have a published free-plan LLM token quota: usage is billed by audio or session duration. AssemblyAI's LLM Gateway is not covered by the free credits and is billed by input/output tokens from the first request. The dashboard's Workspace → Manage → Rate Limits page is authoritative for the current account.

Sources: pre-recorded rate limits, real-time rate limits, billing and pricing, and account management.

For current model selection, use universal-3-5-pro as the recommended pre-recorded and streaming model, with universal-2 as the broad-language fallback. The speech_models request field accepts the pre-recorded model IDs; the v3 streaming WebSocket uses speech_model=universal-3-5-pro.

Key Features and Usage

KeyPool supports AssemblyAI REST APIs for uploads, transcripts, transcript subresources, and streaming-token generation. Use the same KeyPool base URL and team token for upload and transcript requests that belong to the same workflow.

1. Generate a Universal-Streaming Temporary Token

AssemblyAI's current realtime/Universal-Streaming API uses a separate streaming endpoint. Through KeyPool, generate a temporary token with:

curl -G "${KEYPOOL_BASE_URL}/v1/assemblyai/v3/token" \
  -H "Authorization: Bearer ${KEYPOOL_TOKEN}" \
  --data-urlencode "expires_in_seconds=60"

The token can then be used by browser or realtime clients to connect directly to AssemblyAI's WebSocket endpoint:

wss://streaming.assemblyai.com/v3/ws

If your client can send the KeyPool team token on the WebSocket upgrade request, you can also connect through KeyPool:

wss://keypool.example.com/v1/assemblyai/v3/ws?speech_model=universal-3-5-pro&sample_rate=16000

For WebSocket connections through KeyPool, authenticate the upgrade request with the same header used for HTTP requests:

Authorization: Bearer ${KEYPOOL_TOKEN}

Browser WebSocket constructors cannot set custom Authorization headers. Browser clients can either use KeyPool to generate the temporary token and then connect directly to AssemblyAI with the token query parameter, or authenticate the KeyPool WebSocket connection with the generic auth subprotocol:

const ws = new WebSocket(
  `${KEYPOOL_WS_BASE_URL}/v1/assemblyai/v3/ws?speech_model=universal-3-5-pro&sample_rate=16000`,
  [`keypool-token.${KEYPOOL_TOKEN}`],
)

For browser clients that cannot set custom headers, send the KeyPool token with the keypool-token.<token> WebSocket subprotocol shown above.

Do not use the legacy /v2/realtime/token path for new integrations; AssemblyAI's current token endpoint is GET /v3/token?expires_in_seconds=....

2. Transcribe Audio from a URL

Transcribe an audio file available at a URL.

Python Example:

import os
import assemblyai as aai

SAMPLE_AUDIO = "https://assembly.ai/wildfires.mp3"

# Replace with your KeyPool base URL and Team Token
KEYPOOL_BASE_URL = os.environ.get("KEYPOOL_BASE_URL")
KEYPOOL_TOKEN = os.environ.get("KEYPOOL_TOKEN")

# Configure AssemblyAI SDK to use KeyPool
aai.settings.api_key = KEYPOOL_TOKEN
aai.settings.base_url = f"{KEYPOOL_BASE_URL}/v1/assemblyai"

transcriber = aai.Transcriber()
transcript = transcriber.transcribe(SAMPLE_AUDIO)

if transcript.status == aai.TranscriptStatus.completed:
    print(f"Transcript: {transcript.text}")
else:
    print(f"Transcription status: {transcript.status}")

TypeScript Example:

import { AssemblyAI } from "assemblyai";
import { getKeypoolConfig } from "../helpers"; // Assuming helpers is available

const SAMPLE_AUDIO = "https://assembly.ai/wildfires.mp3";

// Replace with your KeyPool base URL and Team Token
const { baseUrl, token } = getKeypoolConfig();

const client = new AssemblyAI({
  apiKey: token,
  baseUrl: `${baseUrl}/v1/assemblyai`,
});

async function transcribeAudio() {
  const transcript = await client.transcripts.transcribe({
    audio: SAMPLE_AUDIO,
  });

  if (transcript.status === "completed") {
    console.log(`Transcript: ${transcript.text}`);
  } else {
    console.log(`Transcription status: ${transcript.status}`);
  }
}

transcribeAudio();

3. Transcribe with Language Detection

Transcribe an audio file and automatically detect its language.

Python Example:

import os
import assemblyai as aai

SAMPLE_AUDIO = "https://assembly.ai/wildfires.mp3"

KEYPOOL_BASE_URL = os.environ.get("KEYPOOL_BASE_URL")
KEYPOOL_TOKEN = os.environ.get("KEYPOOL_TOKEN")

aai.settings.api_key = KEYPOOL_TOKEN
aai.settings.base_url = f"{KEYPOOL_BASE_URL}/v1/assemblyai"

config = aai.TranscriptionConfig(language_detection=True)
transcriber = aai.Transcriber(config=config)
transcript = transcriber.transcribe(SAMPLE_AUDIO)

if transcript.status == aai.TranscriptStatus.completed:
    print(f"Transcript: {transcript.text}")
    print(f"Detected Language: {transcript.language_code}")
else:
    print(f"Transcription status: {transcript.status}")

TypeScript Example:

import { AssemblyAI } from "assemblyai";
import { getKeypoolConfig } from "../helpers";

const SAMPLE_AUDIO = "https://assembly.ai/wildfires.mp3";

const { baseUrl, token } = getKeypoolConfig();

const client = new AssemblyAI({
  apiKey: token,
  baseUrl: `${baseUrl}/v1/assemblyai`,
});

async function transcribeWithLanguageDetection() {
  const transcript = await client.transcripts.transcribe({
    audio: SAMPLE_AUDIO,
    language_detection: true,
  });

  if (transcript.status === "completed") {
    console.log(`Transcript: ${transcript.text}`);
    console.log(`Detected Language: ${transcript.language_code}`);
  } else {
    console.log(`Transcription status: ${transcript.status}`);
  }
}

transcribeWithLanguageDetection();

Error Handling

KeyPool handles various error conditions gracefully, providing informative responses. Common error scenarios include:

  • 401 Unauthorized: Invalid or missing KeyPool Team Token.
  • 403 Forbidden: Your Team Token does not have permission to access the AssemblyAI service.
  • 429 Quota Exceeded: Your team's rate limit for AssemblyAI has been reached.
  • 503 No Available Keys: AssemblyAI is temporarily unavailable through your KeyPool workspace.
  • 502 Upstream Failed: The request to the AssemblyAI API failed (e.g., network error, AssemblyAI API down).

Interactive API Reference

For all AssemblyAI endpoints and in-browser testing, see API Reference → AssemblyAI.