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.
Comprehensive API documentation and guides are available at developers.deepgram.com.
Install the Deepgram Python SDK using pip:
pip install deepgram-sdk- API Reference - Complete reference for all SDK methods and parameters
- WebSocket Reference - Detailed documentation for real-time WebSocket connections
The Deepgram SDK provides both synchronous and asynchronous clients for all major use cases:
Our newest and most advanced speech recognition model with contextual turn detection (WebSocket Reference):
from deepgram import DeepgramClient from deepgram.core.events import EventType client = DeepgramClient() with client.listen.v2.connect( model="flux-general-en", encoding="linear16", sample_rate="16000" ) as connection: def on_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()Transcribe pre-recorded audio files (API Reference):
from deepgram import 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)Generate natural-sounding speech from text (API Reference):
from deepgram import 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())Analyze text for sentiment, topics, and intents (API Reference):
from deepgram import DeepgramClient client = DeepgramClient() response = client.read.v1.text.analyze( request={"text": "Hello, world!"}, language="en", sentiment=True, summarize=True, topics=True, intents=True )Build interactive voice agents (WebSocket Reference):
from deepgram import DeepgramClient from deepgram.extensions.types.sockets import ( AgentV1SettingsMessage, AgentV1Agent, AgentV1AudioConfig, AgentV1AudioInput, AgentV1Listen, AgentV1ListenProvider, AgentV1Think, AgentV1OpenAiThinkProvider, AgentV1SpeakProviderConfig, AgentV1DeepgramSpeakProvider ) client = DeepgramClient() with client.agent.v1.connect() as agent: settings = AgentV1SettingsMessage( audio=AgentV1AudioConfig( input=AgentV1AudioInput(encoding="linear16", sample_rate=44100) ), agent=AgentV1Agent( listen=AgentV1Listen( provider=AgentV1ListenProvider(type="deepgram", model="nova-3") ), think=AgentV1Think( provider=AgentV1OpenAiThinkProvider( type="open_ai", model="gpt-4o-mini" ) ), speak=AgentV1SpeakProviderConfig( provider=AgentV1DeepgramSpeakProvider( type="deepgram", model="aura-2-asteria-en" ) ) ) ) agent.send_settings(settings) agent.start_listening()For comprehensive documentation of all available methods, parameters, and options:
-
API Reference - Complete reference for REST API 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 Reference - Detailed documentation for real-time connections:
- Listen v1/v2: Real-time speech recognition with different model capabilities
- Speak v1: Real-time text-to-speech streaming
- Agent v1: Conversational voice agents with integrated STT, LLM, and TTS
The Deepgram SDK supports two authentication methods:
Use access tokens for temporary or scoped access (recommended for client-side applications):
from deepgram import 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)Use your Deepgram API key for server-side applications:
from deepgram import DeepgramClient # Explicit API key client = DeepgramClient(api_key="YOUR_API_KEY") # Or via environment variable DEEPGRAM_API_KEY client = DeepgramClient()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
The SDK provides full async/await support for non-blocking operations:
import asyncio from deepgram import AsyncDeepgramClient async def main(): 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 def on_message(message): print(f"Received {message.type} event") connection.on(EventType.MESSAGE, on_message) await connection.start_listening() asyncio.run(main())The SDK provides detailed error information for debugging and error handling:
from deepgram import DeepgramClient from deepgram.core.api_error import 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}")Access raw HTTP response data including headers:
from deepgram import 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 objectConfigure timeouts, retries, and other request options:
from deepgram import 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 } )Use a custom httpx client for advanced networking features:
import httpx from deepgram import DeepgramClient client = DeepgramClient( httpx_client=httpx.Client( proxies="http://proxy.example.com", timeout=httpx.Timeout(30.0) ) )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} )We welcome contributions to improve this SDK! However, please note that this library is primarily generated from our API specifications.
-
Install Poetry (if not already installed):
curl -sSL https://install.python-poetry.org | python - -y --version 1.5.1 -
Install dependencies:
poetry install
-
Install example dependencies:
poetry run pip install -r examples/requirements.txt
-
Run tests:
poetry run pytest -rP . -
Run examples:
python -u examples/listen/v2/connect/main.py
See our CONTRIBUTING guide.
- Python 3.8+
- See
pyproject.tomlfor full dependency list
Please see our community code of conduct before contributing to this project.
This project is licensed under the MIT License - see the LICENSE file for details.
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
