Meta

• License: MIT License (MIT)
• Requires: Python <4.0, >=3.10

Classifiers

• Intended Audience
  • Developers
• License
  • OSI Approved :: MIT License
• Operating System
  • MacOS
  • Microsoft :: Windows
  • OS Independent
  • POSIX
  • POSIX :: Linux
• Programming Language
  • Python
  • Python :: 3
  • Python :: 3.10
  • Python :: 3.11
  • Python :: 3.12
  • Python :: 3.13
  • Python :: 3.14
  • Python :: 3.15
• Topic
  • Software Development :: Libraries :: Python Modules
• Typing
  • Typed

Deepgram Python SDK

👁 Built with Fern
👁 PyPI version
👁 Python 3.10+
👁 MIT License

The official Python SDK for Deepgram's automated speech recognition, text-to-speech, and language understanding APIs. Power your applications with world-class speech and Language AI models.

Documentation

Comprehensive API documentation and guides are available at developers.deepgram.com.

Migrating From Earlier Versions

• v6 to v7 (current)
• v5 to v6
• v3+ to v5
• v2 to v3+

Installation

Install the Deepgram Python SDK using pip:

pipinstalldeepgram-sdk

Reference

• API Reference - Complete reference for all SDK methods, parameters, and WebSocket connections

Usage

Quick Start

The Deepgram SDK provides both synchronous and asynchronous clients for all major use cases:

Real-time Speech Recognition (Listen v2)

Our newest and most advanced speech recognition model with contextual turn detection (Reference):

fromdeepgramimport DeepgramClient
fromdeepgram.core.eventsimport EventType

client = DeepgramClient()

with client.listen.v2.connect(
 model="flux-general-en",
 encoding="linear16",
 sample_rate=16000
) as connection:
 defon_message(message):
 print(f"Received {message.type} event")

 connection.on(EventType.OPEN, lambda _: print("Connection opened"))
 connection.on(EventType.MESSAGE, on_message)
 connection.on(EventType.CLOSE, lambda _: print("Connection closed"))
 connection.on(EventType.ERROR, lambda error: print(f"Error: {error}"))

 # Start listening and send audio data
 connection.start_listening()

File Transcription

Transcribe pre-recorded audio files (API Reference):

fromdeepgramimport DeepgramClient

client = DeepgramClient()

with open("audio.wav", "rb") as audio_file:
 response = client.listen.v1.media.transcribe_file(
 request=audio_file.read(),
 model="nova-3"
 )
 print(response.results.channels[0].alternatives[0].transcript)

Text-to-Speech

Generate natural-sounding speech from text (API Reference):

fromdeepgramimport DeepgramClient

client = DeepgramClient()

response = client.speak.v1.audio.generate(
 text="Hello, this is a sample text to speech conversion."
)

# Save the audio file
with open("output.mp3", "wb") as audio_file:
 audio_file.write(response.stream.getvalue())

Text Analysis

Analyze text for sentiment, topics, and intents (API Reference):

fromdeepgramimport DeepgramClient

client = DeepgramClient()

response = client.read.v1.text.analyze(
 request={"text": "Hello, world!"},
 language="en",
 sentiment=True,
 summarize=True,
 topics=True,
 intents=True
)

Voice Agent (Conversational AI)

Build interactive voice agents (Reference):

fromdeepgramimport DeepgramClient
fromdeepgram.agent.v1.typesimport (
 AgentV1Settings, AgentV1SettingsAgent,
 AgentV1SettingsAgentListen, AgentV1SettingsAgentListenProvider_V1,
 AgentV1SettingsAudio, AgentV1SettingsAudioInput,
)
fromdeepgram.types.think_settings_v1import ThinkSettingsV1
fromdeepgram.types.think_settings_v1providerimport ThinkSettingsV1Provider_OpenAi
fromdeepgram.types.speak_settings_v1import SpeakSettingsV1
fromdeepgram.types.speak_settings_v1providerimport SpeakSettingsV1Provider_Deepgram

client = DeepgramClient()

with client.agent.v1.connect() as agent:
 settings = AgentV1Settings(
 audio=AgentV1SettingsAudio(
 input=AgentV1SettingsAudioInput(encoding="linear16", sample_rate=24000)
 ),
 agent=AgentV1SettingsAgent(
 listen=AgentV1SettingsAgentListen(
 provider=AgentV1SettingsAgentListenProvider_V1(
 type="deepgram", model="nova-3"
 )
 ),
 think=ThinkSettingsV1(
 provider=ThinkSettingsV1Provider_OpenAi(
 type="open_ai", model="gpt-4o-mini"
 ),
 prompt="You are a helpful AI assistant.",
 ),
 speak=SpeakSettingsV1(
 provider=SpeakSettingsV1Provider_Deepgram(
 type="deepgram", model="aura-2-asteria-en"
 )
 ),
 ),
 )

 agent.send_settings(settings)
 agent.start_listening()

Complete SDK Reference

For comprehensive documentation of all available methods, parameters, and options:

• API Reference - Complete reference for all SDK methods including:

  • Listen (Speech-to-Text): File transcription, URL transcription, and media processing
  • Speak (Text-to-Speech): Audio generation and voice synthesis
  • Read (Text Intelligence): Text analysis, sentiment, summarization, and topic detection
  • Manage: Project management, API keys, and usage analytics
  • Auth: Token generation and authentication management
  • WebSocket connections: Listen v1/v2, Speak v1, and Agent v1 real-time streaming

Authentication

The Deepgram SDK supports two authentication methods:

Access Token Authentication

Use access tokens for temporary or scoped access (recommended for client-side applications):

fromdeepgramimport DeepgramClient

# Explicit access token
client = DeepgramClient(access_token="YOUR_ACCESS_TOKEN")

# Or via environment variable DEEPGRAM_TOKEN
client = DeepgramClient()

# Generate access tokens using your API key
auth_client = DeepgramClient(api_key="YOUR_API_KEY")
token_response = auth_client.auth.v1.tokens.grant()
token_client = DeepgramClient(access_token=token_response.access_token)

API Key Authentication

Use your Deepgram API key for server-side applications:

fromdeepgramimport DeepgramClient

# Explicit API key
client = DeepgramClient(api_key="YOUR_API_KEY")

# Or via environment variable DEEPGRAM_API_KEY
client = DeepgramClient()

Environment Variables

The SDK automatically discovers credentials from these environment variables:

• DEEPGRAM_TOKEN - Your access token (takes precedence)
• DEEPGRAM_API_KEY - Your Deepgram API key

Precedence: Explicit parameters > Environment variables

Async Client

The SDK provides full async/await support for non-blocking operations:

importasyncio
fromdeepgramimport AsyncDeepgramClient

async defmain():
 client = AsyncDeepgramClient()

 # Async file transcription
 with open("audio.wav", "rb") as audio_file:
 response = await client.listen.v1.media.transcribe_file(
 request=audio_file.read(),
 model="nova-3"
 )

 # Async WebSocket connection
 async with client.listen.v2.connect(
 model="flux-general-en",
 encoding="linear16",
 sample_rate=16000
 ) as connection:
 async defon_message(message):
 print(f"Received {message.type} event")

 connection.on(EventType.MESSAGE, on_message)
 await connection.start_listening()

asyncio.run(main())

Exception Handling

The SDK provides detailed error information for debugging and error handling:

fromdeepgramimport DeepgramClient
fromdeepgram.core.api_errorimport ApiError

client = DeepgramClient()

try:
 response = client.listen.v1.media.transcribe_file(
 request=audio_data,
 model="nova-3"
 )
except ApiError as e:
 print(f"Status Code: {e.status_code}")
 print(f"Error Details: {e.body}")
 print(f"Request ID: {e.headers.get('x-dg-request-id','N/A')}")
except Exception as e:
 print(f"Unexpected error: {e}")

Advanced Features

Raw Response Access

Access raw HTTP response data including headers:

fromdeepgramimport DeepgramClient

client = DeepgramClient()

response = client.listen.v1.media.with_raw_response.transcribe_file(
 request=audio_data,
 model="nova-3"
)

print(response.headers) # Access response headers
print(response.data) # Access the response object

Request Configuration

Configure timeouts, retries, and other request options:

fromdeepgramimport DeepgramClient

# Global client configuration
client = DeepgramClient(timeout=30.0)

# Per-request configuration
response = client.listen.v1.media.transcribe_file(
 request=audio_data,
 model="nova-3",
 request_options={
 "timeout_in_seconds": 60,
 "max_retries": 3
 }
)

Custom HTTP Client

Use a custom httpx client for advanced networking features:

importhttpx
fromdeepgramimport DeepgramClient

client = DeepgramClient(
 httpx_client=httpx.Client(
 proxies="http://proxy.example.com",
 timeout=httpx.Timeout(30.0)
 )
)

Custom Transports

Replace the built-in websockets transport with your own implementation for WebSocket-based APIs (Listen, Speak, Agent). This enables alternative protocols (HTTP/2, SSE), test doubles, or proxied connections.

Any class that implements the right methods can be used as a transport — no inheritance required. Pass your class (or a factory callable) as transport_factory when creating a client.

Sync transports

Implement send(), recv(), __iter__(), and close(), then pass the class to DeepgramClient:

fromdeepgramimport DeepgramClient
fromdeepgram.core.eventsimport EventType

classMyTransport:
 def__init__(self, url: str, headers: dict):
 ... # establish your connection

 defsend(self, data): ... # send str or bytes
 defrecv(self): ... # return next message
 def__iter__(self): ... # yield messages until closed
 defclose(self): ... # tear down connection

client = DeepgramClient(api_key="...", transport_factory=MyTransport)

with client.listen.v1.connect(model="nova-3") as connection:
 connection.on(EventType.MESSAGE, on_message)
 connection.start_listening()

Async transports

Implement async def send(), async def recv(), async def __aiter__(), and async def close(), then use AsyncDeepgramClient:

fromdeepgramimport AsyncDeepgramClient

client = AsyncDeepgramClient(api_key="...", transport_factory=MyAsyncTransport)

async with client.listen.v1.connect(model="nova-3") as connection:
 connection.on(EventType.MESSAGE, on_message)
 await connection.start_listening()

See src/deepgram/transport_interface.py for the full protocol definitions (SyncTransport and AsyncTransport).

SageMaker transport

The deepgram-sagemaker package (source) is a ready-made async transport for running Deepgram models on AWS SageMaker endpoints. It uses HTTP/2 bidirectional streaming under the hood, but exposes the same SDK interface — just install the package and swap in a transport_factory:

pipinstalldeepgram-sagemaker# requires Python 3.12+

fromdeepgramimport AsyncDeepgramClient
fromdeepgram_sagemakerimport SageMakerTransportFactory

factory = SageMakerTransportFactory(
 endpoint_name="my-deepgram-endpoint",
 region="us-west-2",
)

# SageMaker uses AWS credentials (not Deepgram API keys)
client = AsyncDeepgramClient(api_key="unused", transport_factory=factory)

async with client.listen.v1.connect(model="nova-3") as connection:
 connection.on(EventType.MESSAGE, on_message)
 await connection.start_listening()

Note: The SageMaker transport is async-only and requires AsyncDeepgramClient.

See examples/27-transcription-live-sagemaker.py for a complete working example.

Retry Configuration

The SDK automatically retries failed requests with exponential backoff:

# Automatic retries for 408, 429, and 5xx status codes
response = client.listen.v1.media.transcribe_file(
 request=audio_data,
 model="nova-3",
 request_options={"max_retries": 3}
)

Contributing

We welcome contributions to improve this SDK! However, please note that this library is primarily generated from our API specifications.

Development Setup

1. Install Poetry (if not already installed):

   curl-sSLhttps://install.python-poetry.org|python--y--version1.5.1
   

2. Install dependencies:

   poetryinstall
   

3. Install example dependencies:

   poetryrunpipinstall-rexamples/requirements.txt
   

4. Run tests:

   poetryrunpytest-rP.
   

5. Run examples:

   python-uexamples/07-transcription-live-websocket.py
   

Contribution Guidelines

See our CONTRIBUTING guide.

Requirements

• Python 3.10+
• See pyproject.toml for full dependency list

Community Code of Conduct

Please see our community code of conduct before contributing to this project.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Verified details

These details have been verified by PyPI

Maintainers

👁 Avatar for deepgram from gravatar.com
deepgram

Unverified details

These details have not been verified by PyPI

Project links

• Repository

• Download URL: deepgram_sdk-7.3.1.tar.gz
• Upload date: Jun 3, 2026
• Size: 208.3 kB
• Tags: Source
• Uploaded using Trusted Publishing? No
• Uploaded via: poetry/1.5.1 CPython/3.10.20 Linux/6.17.0-1015-azure

Hashes for deepgram_sdk-7.3.1.tar.gz

Algorithm	Hash digest
SHA256	eaade4ea4bead9f009490cf20dcec09a0abd184af112e8a5ddb50cc82b7f98b9
MD5	c43ac95e41ac44586bb7d128dfe05f1a
BLAKE2b-256	1ef472418cc556fbf08216a1cdd66b11affb4077bbd749c1d6b0e77043b87fd2

See more details on using hashes here.

• Download URL: deepgram_sdk-7.3.1-py3-none-any.whl
• Upload date: Jun 3, 2026
• Size: 559.9 kB
• Tags: Python 3
• Uploaded using Trusted Publishing? No
• Uploaded via: poetry/1.5.1 CPython/3.10.20 Linux/6.17.0-1015-azure

Hashes for deepgram_sdk-7.3.1-py3-none-any.whl

Algorithm	Hash digest
SHA256	57b01059240ee8193116773a7b1cec7d36802cee8c26d69939601c2497d1aafa
MD5	ff1be576d1aeb1e9b4ee9dd207c06a31
BLAKE2b-256	a22512535afe1c5e70988bc385109d2161f35d5e125ef52bef4bff25e018ca56

See more details on using hashes here.