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.

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-streaming-english&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-streaming-english&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.