assemblyai-python-sdk CLAUDE.md

AssemblyAI Python SDK

Speech-to-text and audio intelligence SDK. Supports pre-recorded transcription, real-time streaming, and audio analysis features.

Quick start

pip install -U assemblyai

import os
import assemblyai as aai

aai.settings.api_key = os.environ["ASSEMBLYAI_API_KEY"]

transcript = aai.Transcriber().transcribe(
    "https://example.com/audio.mp3",
    config=aai.TranscriptionConfig(
        speech_models=["universal-3-5-pro", "universal-2"],
        speaker_labels=True,
    ),
)

print(transcript.text)
for utterance in transcript.utterances:
    print(f"Speaker {utterance.speaker}: {utterance.text}")

Auth

Set ASSEMBLYAI_API_KEY as an environment variable, or:

aai.settings.api_key = "your-key"

Key classes

• aai.Transcriber — Transcribe files, URLs, or streams. Methods: transcribe(), transcribe_async(), submit(), list_transcripts()
• aai.AsyncTranscriber — Asyncio counterpart of Transcriber. Same options, every API call a coroutine. Methods: transcribe(), submit(), transcribe_group(), get_by_id(), delete_by_id(), list_transcripts(), upload_file()
• aai.AsyncTranscript — What AsyncTranscriber returns. Same fields as Transcript, coroutine methods
• aai.AsyncClient — Shared httpx.AsyncClient pool for one or more AsyncTranscribers
• assemblyai.prerecorded.v2 — Canonical module for both transcribers, matching the /v2/transcript API. The top-level aai.* names re-export it
• aai.TranscriptionConfig — All transcription options: speech_models, speaker_labels, sentiment_analysis, entity_detection, auto_chapters, content_safety, language_detection, summarization, word_boost, disfluencies
• aai.Transcript — Result object with .text, .status, .utterances, .words, .chapters, .entities, .sentiment_analysis. Methods: get_sentences(), get_paragraphs(), export_subtitles_srt(), export_subtitles_vtt()
• aai.SyncTranscriber — Synchronous pre-recorded transcription: audio in, transcript out, one request (no polling). Methods: transcribe(), transcribe_async()
• aai.AsyncSyncTranscriber — Asyncio counterpart of SyncTranscriber. Same input types, config, result, and errors; transcribe() and warm() are coroutines. Owns an HTTP pool: use async with or await aclose(), or pass an aai.AsyncClient to share one
• aai.SyncTranscriptionConfig — Sync options: model (default universal-3-5-pro), prompt, keyterms_prompt, conversation_context, language_codes, timestamps, sample_rate, channels
• aai.SyncTranscriptResponse — Sync result: .text, .words (SyncWord with confidence always, start/end only when timestamps=True), .confidence, .audio_duration_ms, .session_id, .request_time_ms
• assemblyai.streaming.v3.RealTimeTranscriber — Real-time streaming with event-based API (threaded)
• assemblyai.streaming.v3.AsyncRealTimeTranscriber — Asyncio-native counterpart; same options/events