AssemblyAI Python SDK

Warnings

• gotcha The official Python SDK is primarily intended for testing and light usage. For high-scale or production traffic, it is recommended to call the AssemblyAI API directly via HTTP requests for best results.
  Fix: For production-level scaling, consider implementing direct HTTP calls to the AssemblyAI API, following their official documentation for HTTP code examples.
• breaking The LeMUR API will be deprecated on March 31, 2026, and will no longer function after this date. Users must migrate to the LLM Gateway for continued access to language model capabilities.
  Fix: Migrate your LeMUR integrations to use AssemblyAI's LLM Gateway by March 31, 2026. Refer to the official migration guide for details.
• gotcha Always store your AssemblyAI API key securely as an environment variable (e.g., `ASSEMBLYAI_API_KEY`) and avoid hardcoding it directly into your code or committing it to version control.
  Fix: Use `os.environ.get("ASSEMBLYAI_API_KEY")` to retrieve your API key. Ensure your `.env` file is excluded from version control (e.g., via `.gitignore`).
• gotcha The default read operation timeout in the Python SDK is 15 seconds. Longer audio files or slow network conditions may lead to 'read operation timed out' errors.
  Fix: Increase the timeout value if experiencing timeouts, though the documentation for how to explicitly set this in the latest SDK version isn't immediately clear in search results. Check the latest SDK docs or consider direct API calls for fine-grained control.
• gotcha For optimal accuracy, specify current speech models. For asynchronous transcription, use `speech_models=["universal-3-pro", "universal-2"]`. For streaming, use `u3-rt-pro`. Older default models may have reduced performance.
  Fix: Pass `config=aai.TranscriptionConfig(speech_models=["universal-3-pro"])` (or other desired models) to `Transcriber()` or the `.transcribe()` method. For streaming, ensure `u3-rt-pro` is used if applicable.
• breaking As of December 2025, security controls were tightened for pre-recorded file transcription. API tokens must now belong to the same project that originally uploaded the file to transcribe it, preventing cross-project access.
  Fix: Ensure that the API token used for transcription belongs to the same AssemblyAI project where the audio file was uploaded.

Install

• pip install -U assemblyai Install the AssemblyAI SDK

Imports

• assemblyai

  import assemblyai as aai

  Standard alias for the SDK.
• Transcriber

  transcriber = aai.Transcriber()

  Initializes the transcription client.
• TranscriptionConfig

  config = aai.TranscriptionConfig(punctuate=True)

  Used to configure transcription options like punctuation, speaker labels, or model.
• StreamingClient

  client = aai.StreamingClient()

  Used for real-time, streaming transcription from a microphone or other live audio source.

Quickstart

This quickstart transcribes an audio file from a publicly accessible URL. It retrieves the API key from an environment variable `ASSEMBLYAI_API_KEY` for security. The `Transcriber` handles the transcription process, including polling for completion.

import assemblyai as aai
import os

aai.settings.api_key = os.environ.get("ASSEMBLYAI_API_KEY", "")

if not aai.settings.api_key:
    raise ValueError("ASSEMBLYAI_API_KEY environment variable not set.")

transcriber = aai.Transcriber()

audio_url = (
    "https://storage.googleapis.com/aai-web-samples/5_9_2023_Microsoft_Build_Keynote.mp3"
)

print(f"Transcribing audio from URL: {audio_url}")
transcript = transcriber.transcribe(audio_url)

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