Install & Compatibility
Where this runs
tested against v1.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.884s · 33.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.2s · import 0.804s · 33MB
32MB installed
● package 32MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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)
assemblyai --version
Debug
Known issues
gotchaThe 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.fixFor production-level scaling, consider implementing direct HTTP calls to the AssemblyAI API, following their official documentation for HTTP code examples.
affects: All versions
breakingThe 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.fixMigrate your LeMUR integrations to use AssemblyAI's LLM Gateway by March 31, 2026. Refer to the official migration guide for details.
affects: All versions using LeMUR after March 31, 2026
gotchaAlways 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.fixUse `os.environ.get("ASSEMBLYAI_API_KEY")` to retrieve your API key. Ensure your `.env` file is excluded from version control (e.g., via `.gitignore`). affects: All versions
gotchaThe 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.fixIncrease 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.
affects: All versions
gotchaFor 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.fixPass `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.
affects: All versions (best practice)
breakingAs 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.fixEnsure that the API token used for transcription belongs to the same AssemblyAI project where the audio file was uploaded.
affects: Versions after December 2025
Upgrade
Version history
1.0.0latest on PyPI · released Aug 14, 2026
Audit
Dependencies
No dependency data recorded yet.