Meta

• License: MIT License (MIT License)
• Author: AssemblyAI
• Requires: Python >=3.8
• Provides-Extra: extras

Classifiers

• Development Status
  • 3 - Alpha
• Intended Audience
  • Developers
  • Science/Research
• License
  • OSI Approved :: MIT License
• Natural Language
  • English
• Programming Language
  • Python :: 3
  • Python :: 3.8
  • Python :: 3.9
  • Python :: 3.10
  • Python :: 3.11
  • Python :: 3.12
  • Python :: 3.13
  • Python :: 3.14
• Topic
  • Scientific/Engineering :: Artificial Intelligence
  • Software Development :: Libraries
  • Software Development :: Libraries :: Python Modules

👁 Image

---

👁 CI Passing
👁 GitHub License
👁 PyPI version
👁 PyPI Python Versions
👁 PyPI - Wheel
👁 AssemblyAI Twitter
👁 AssemblyAI YouTube
👁 Discord

AssemblyAI's Python SDK

Build with AI models that can transcribe and understand audio

With a single API call, get access to AI models built on the latest AI breakthroughs to transcribe and understand audio and speech data securely at large scale.

Using with AI coding agents

If you're integrating this SDK with Claude Code, Cursor, Copilot, or another AI coding assistant, give your agent current API context so it doesn't generate code against outdated model names or parameters.

The most effective option is project instructions. Add this to your CLAUDE.md, .cursorrules, AGENTS.md, or equivalent agent instructions file:

Always fetch https://assemblyai.com/docs/llms.txt before writing AssemblyAI code. The API has changed, do not rely on memorized parameter names.

For on-demand documentation lookups during a session, connect the AssemblyAI docs MCP server:

claude mcp add assemblyai-docs --transport http https://mcp.assemblyai.com/docs

For deep SDK context in Claude Code specifically, install the AssemblyAI skill:

claude install-skill https://github.com/AssemblyAI/assemblyai-skill

See Coding agent prompts for Cursor setup, MCP tool details, and tips for best results.

Overview

• AssemblyAI's Python SDK
• Overview
• Documentation
• Quick Start
  • Installation
  • Examples
    • Core Examples
    • Speech Understanding Examples
    • Streaming Examples
    • Change the default settings
  • Playground
• Advanced
  • How the SDK handles Default Configurations
    • Defining Defaults
    • Overriding Defaults
  • Synchronous vs Asynchronous
  • Getting the HTTP status code
  • Polling Intervals
  • Retrieving Existing Transcripts
    • Retrieving a Single Transcript
    • Retrieving Multiple Transcripts as a Group
    • Retrieving Transcripts Asynchronously

Documentation

Visit our AssemblyAI API Documentation to get an overview of our models!

Quick Start

Installation

pipinstall-Uassemblyai

Examples

Before starting, you need to set the API key. If you don't have one yet, sign up for one!

importassemblyaiasaai

# set the API key
aai.settings.api_key = f"{ASSEMBLYAI_API_KEY}"

---

Core Examples

---

Speech Understanding Examples

---

Streaming Examples

Real-time speech-to-text via WebSocket against the u3-rt-pro model. The SDK ships two clients with identical option/event/handler surfaces — StreamingClient (threaded) and AsyncStreamingClient (asyncio). Pick whichever fits your codebase.

Handler contract: every handler is called as handler(client, event). Plain functions and async def functions both work; AsyncStreamingClient awaits async handlers inline on the read task, so don't block — use asyncio.create_task(...) if you need concurrent work.

Read more about the streaming service.

---

Change the default settings

You'll find the Settings class with all default values in types.py.

---

Playground

Visit our Playground to try our all of our Speech AI models and LeMUR for free:

• Playground

Advanced

How the SDK handles Default Configurations

Defining Defaults

When no TranscriptionConfig is being passed to the Transcriber or its methods, it will use a default instance of a TranscriptionConfig.

If you would like to re-use the same TranscriptionConfig for all your transcriptions, you can set it on the Transcriber directly:

config = aai.TranscriptionConfig(punctuate=False, format_text=False)

transcriber = aai.Transcriber(config=config)

# will use the same config for all `.transcribe*(...)` operations
transcriber.transcribe("https://example.org/audio.wav")

Overriding Defaults

You can override the default configuration later via the .config property of the Transcriber:

transcriber = aai.Transcriber()

# override the `Transcriber`'s config with a new config
transcriber.config = aai.TranscriptionConfig(punctuate=False, format_text=False)

In case you want to override the Transcriber's configuration for a specific operation with a different one, you can do so via the config parameter of a .transcribe*(...) method:

config = aai.TranscriptionConfig(punctuate=False, format_text=False)
# set a default configuration
transcriber = aai.Transcriber(config=config)

transcriber.transcribe(
 "https://example.com/audio.mp3",
 # overrides the above configuration on the `Transcriber` with the following
 config=aai.TranscriptionConfig(speech_models=["universal-3-pro", "universal-2"], multichannel=True, disfluencies=True)
)

Synchronous vs Asynchronous

Currently, the SDK provides two ways to transcribe audio files.

The synchronous approach halts the application's flow until the transcription has been completed.

The asynchronous approach allows the application to continue running while the transcription is being processed. The caller receives a concurrent.futures.Future object which can be used to check the status of the transcription at a later time.

You can identify those two approaches by the _async suffix in the Transcriber's method name (e.g. transcribe vs transcribe_async).

Getting the HTTP status code

There are two ways of accessing the HTTP status code:

• All custom AssemblyAI Error classes have a status_code attribute.
• The latest HTTP response is stored in aai.Client.get_default().latest_response after every API call. This approach works also if no Exception is thrown.

transcriber = aai.Transcriber()

# Option 1: Catch the error
try:
 transcript = transcriber.submit("./example.mp3")
except aai.AssemblyAIError as e:
 print(e.status_code)

# Option 2: Access the latest response through the client
client = aai.Client.get_default()

try:
 transcript = transcriber.submit("./example.mp3")
except:
 print(client.last_response)
 print(client.last_response.status_code)

Polling Intervals

By default we poll the Transcript's status each 3s. In case you would like to adjust that interval:

importassemblyaiasaai

aai.settings.base_url = "https://api.assemblyai.com"
aai.settings.api_key = "YOUR_API_KEY"

aai.settings.polling_interval = 1.0

Retrieving Existing Transcripts

Retrieving a Single Transcript

If you previously created a transcript, you can use its ID to retrieve it later.

importassemblyaiasaai

aai.settings.base_url = "https://api.assemblyai.com"
aai.settings.api_key = "YOUR_API_KEY"

transcript = aai.Transcript.get_by_id("<TRANSCRIPT_ID>")

print(transcript.id)
print(transcript.text)

Retrieving Multiple Transcripts as a Group

You can also retrieve multiple existing transcripts and combine them into a single TranscriptGroup object. This allows you to perform operations on the transcript group as a single unit.

importassemblyaiasaai

aai.settings.base_url = "https://api.assemblyai.com"
aai.settings.api_key = "YOUR_API_KEY"

transcript_group = aai.TranscriptGroup.get_by_ids(["<TRANSCRIPT_ID_1>", "<TRANSCRIPT_ID_2>"])

Retrieving Transcripts Asynchronously

Both Transcript.get_by_id and TranscriptGroup.get_by_ids have asynchronous counterparts, Transcript.get_by_id_async and TranscriptGroup.get_by_ids_async, respectively. These functions immediately return a Future object, rather than blocking until the transcript(s) are retrieved.

See the above section on Synchronous vs Asynchronous for more information.

Verified details

These details have been verified by PyPI

Maintainers

👁 Avatar for assemblyai from gravatar.com
assemblyai

Unverified details

These details have not been verified by PyPI

Project links

• Homepage
• API Documentation
• Code
• Documentation
• Issues
• Website

• Download URL: assemblyai-0.64.21.tar.gz
• Upload date: Jun 16, 2026
• Size: 93.2 kB
• Tags: Source
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/6.1.0 CPython/3.13.12

Hashes for assemblyai-0.64.21.tar.gz

Algorithm	Hash digest
SHA256	51c650c601c8be4bad8a20f3bbc3619f6f914fb6bc66ed6b867eb7c80b341873
MD5	4dbc95c0fd631df9b63b22e71465b1af
BLAKE2b-256	5f2e51726cb411af2972336c754742234a8113401d5e047afbe9395bb414378c

See more details on using hashes here.

• Download URL: assemblyai-0.64.21-py3-none-any.whl
• Upload date: Jun 16, 2026
• Size: 81.8 kB
• Tags: Python 3
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/6.1.0 CPython/3.13.12

Hashes for assemblyai-0.64.21-py3-none-any.whl

Algorithm	Hash digest
SHA256	3604635990ec4d95878879e816d4300df13e6507c566054d2cee39a6c595ebae
MD5	ba9236d512b876064d8feb909b613180
BLAKE2b-256	bae1a107d6824dc80894fcc1b6c5324a638994509955d50d2ca92c107cc02b8c

See more details on using hashes here.