Registry / ai-ml / deepgram-sdk

deepgram-sdk

JSON →
library7.7.1pypypi✓ verified 26d ago

The official Python SDK for Deepgram's automated speech recognition, text-to-speech, and language understanding APIs. It enables developers to integrate world-class speech and Language AI models into their applications. The library is actively maintained with frequent releases, currently at version 6.1.1.

pip install deepgram-sdk
INSTALL
IMPORT
SIG · DEEPGRAM-SDK
D
deepgram-sdk
ai-mlpythonv7.7.1
Install
4.7s avg
Import
713ms
Disk
41MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v7.7.1 · 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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.730s · 42.4MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 4.7s · import 0.696s · 42MB
41MB installed
● package 41MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

DeepgramClient
from deepgram import DeepgramClient
from deepgram import Deepgram
The `Deepgram` client was used in v5 and earlier; `DeepgramClient` is the current client in v6.
EventType
from deepgram.core.events import EventType
Used for handling WebSocket events.
ListenV2Options
from deepgram.listen.v2.options import ListenV2Options
Types are now imported from their feature-specific namespaces in v6.

This quickstart demonstrates how to initialize the DeepgramClient, configure it with an API key from environment variables, and establish a real-time WebSocket connection to the Deepgram Listen API (v2) for transcribing audio. It includes basic event handlers for connection status and incoming transcripts.

import os from deepgram import DeepgramClient, DeepgramClientOptions, LiveTranscriptionEvents # Ensure you have your Deepgram API key set as an environment variable (DEEPGRAM_API_KEY or DEEPGRAM_TOKEN) API_KEY = os.environ.get('DEEPGRAM_API_KEY') or os.environ.get('DEEPGRAM_TOKEN') if not API_KEY: raise ValueError("DEEPGRAM_API_KEY or DEEPGRAM_TOKEN environment variable not set.") # Configure the client options for best performance and compatibility config = DeepgramClientOptions(verbose=1) deepgram = DeepgramClient(API_KEY, config=config) # For real-time streaming, connect to the Listen API # This example demonstrates a synchronous connection for simplicity, # but async methods are also available. def main(): try: # Connect to the real-time Listen API (v2) connection = deepgram.listen.v2.live.connect() # Define event handlers def on_message(self, result, **kwargs): if result.speech_final: # Only print final transcripts print(f"Speaker: {result.speaker}") # Assuming speaker diarization is enabled print(f"Transcript: {result.channel.alternatives[0].transcript}") def on_open(self, open, **kwargs): print("Connection opened.") def on_close(self, close, **kwargs): print("Connection closed.") def on_error(self, error, **kwargs): print(f"Error: {error}") # Register event handlers connection.on(LiveTranscriptionEvents.Open, on_open) connection.on(LiveTranscriptionEvents.Transcript, on_message) connection.on(LiveTranscriptionEvents.Close, on_close) connection.on(LiveTranscriptionEvents.Error, on_error) # Start sending audio data (in a real app, this would be from a microphone or audio file) # For this example, we'll just send a dummy message and close. print("Sending dummy data... (in a real app, send actual audio bytes)") # In a real application, you would continuously send bytes from an audio source: # connection.send_data(audio_chunk_bytes) # For now, simulate sending options connection.send_options({ "model": "nova-2", "language": "en-US", "punctuate": True, "diarize": True, "smart_format": True }) import time time.sleep(5) # Keep connection open for a bit to simulate processing # Don't forget to close the connection when done connection.finish() except Exception as e: print(f"Could not open connection: {e}") if __name__ == "__main__": main()
Debug
Known issues
breakingVersion 6.0.0 introduced significant breaking changes, including a complete overhaul of WebSocket clients. Hand-rolled WebSocket code from v5 has been replaced by fully generated clients for Listen v1/v2, Speak v1, and Agent v1.
fix
Review the official migration guide from v5 to v6. Update all WebSocket client instantiations and interaction patterns.
affects: >=6.0.0
breakingThe `send_media()` method for WebSocket clients now exclusively accepts raw `bytes` for audio data. Control messages (like keep-alive, finalize, flush) have been replaced by dedicated methods (`send_keep_alive()`, `send_finalize()`, `send_flush()`) instead of the generic `send_control({'type': '...'})` pattern.
fix
Ensure audio data is converted to `bytes` before sending via `send_media()`. Replace calls to `send_control()` with the new specific control methods.
affects: >=6.0.0
breakingThe type system in v6 has shifted to domain-specific imports. Types are now imported from their respective feature namespaces (e.g., `deepgram.listen.v1.types`, `deepgram.agent.v1.types`) instead of a shared 'barrel' module.
fix
Update all type import statements to reflect the new module structure (e.g., `from deepgram.listen.v1.options import ListenV1Options`).
affects: >=6.0.0
breakingThe SageMaker transport functionality has been extracted into a separate package, `deepgram-sagemaker`. It is no longer part of the core `deepgram-sdk`.
fix
If using SageMaker transport, install the `deepgram-sagemaker` package separately (`pip install deepgram-sagemaker`).
affects: >=6.0.0
gotchaWhen providing authentication credentials, the SDK prioritizes environment variables. Specifically, `DEEPGRAM_TOKEN` takes precedence over `DEEPGRAM_API_KEY`. Explicit `access_token` or `api_key` parameters during `DeepgramClient` initialization take the highest precedence.
fix
Be aware of the authentication priority: explicit parameter > `DEEPGRAM_TOKEN` env var > `DEEPGRAM_API_KEY` env var. Always ensure the correct API key or token is being used based on your configuration.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'deepgram'
The `deepgram-sdk` package is not installed or the Python environment where the code is run does not have it installed.
fix
Ensure the deepgram-sdk is installed in your active Python environment: `pip install deepgram-sdk`
DeepgramSetupError: Invalid API key
The Deepgram SDK was initialized with an API key that is invalid, expired, or has incorrect formatting (e.g., leading/trailing whitespace).
fix
Verify your Deepgram API key in the Deepgram Console, ensuring it is correct, active, and copied without extra characters. Pass the correct key to `DeepgramClient(api_key="YOUR_API_KEY")` or set the `DEEPGRAM_API_KEY` environment variable.
TypeError: got an unexpected keyword argument 'extra_headers'
This error typically occurs due to an incompatibility between the `deepgram-sdk` and a newer version of the `websockets` library, where the `extra_headers` parameter was renamed or changed.
fix
Downgrade the `websockets` library to a compatible version, often `websockets<14` (e.g., `pip install 'websockets<14'`)
401 Unauthorized
The request to the Deepgram API was made without a valid API key, or the provided API key is incorrect or lacks the necessary permissions.
fix
Provide a valid Deepgram API key via the `Authorization` header, the `api_key` parameter in the SDK client, or the `DEEPGRAM_API_KEY` environment variable. Ensure the key has the required permissions for the endpoint you are accessing.
422 Unprocessable Entity
Deepgram was unable to process the request, commonly because the audio data sent was incomplete, corrupted, or in an unsupported format, or the connection was closed prematurely.
fix
Verify that the audio data is valid, complete, and in a format supported by Deepgram. Ensure the streaming connection remains open until all audio is sent, and check client-side logs for interrupted uploads or timeouts.
Upgrade
Version history
7.7.1latest on PyPI · released Aug 25, 2026
Audit
Dependencies
deepgram-sagemakeroptionalRequired for using Deepgram models on AWS SageMaker endpoints.
Agent activity
26 hits · last 30 days
node
23
OpenAI (training)
1
Resources
deepgram-sdk — pip install deepgram-sdk · libregistry