Official Python SDK for Deepgram. Power your apps with world-class speech and Language AI models.
- Documentation
- Migrating from earlier versions
- Requirements
- Installation
- Initialization
- Pre-Recorded (Synchronous)
- Pre-Recorded (Asynchronous / Callbacks)
- Streaming Audio
- Transcribing to Captions
- Voice Agent
- Text to Speech REST
- Text to Speech Streaming
- Text Intelligence
- Authentication
- Projects
- Keys
- Members
- Scopes
- Invitations
- Usage
- Billing
- Models
- On-Prem APIs
- Logging
- Backwards Compatibility
- Development and Contributing
- Getting Help
You can learn more about the Deepgram API at developers.deepgram.com.
We have published a migration guide on our docs, showing how to move from v2 to v3.
The Voice Agent interfaces have been updated to use the new Voice Agent V1 API. Please refer to our Documentation on Migration to new V1 Agent API.
Python (version ^3.10)
To install the latest version available:
pip install deepgram-sdkAll of the examples below will require DeepgramClient.
fromdeepgramimportDeepgramClient# Initialize the clientdeepgram=DeepgramClient("YOUR_API_KEY") # Replace with your API key🔑 To access the Deepgram API you will need a free Deepgram API Key.
Transcribe audio from a URL.
fromdeepgramimportPrerecordedOptionsresponse=deepgram.listen.rest.v("1").transcribe_url( source={"url": "https://dpgr.am/spacewalk.wav"}, options=PrerecordedOptions(model="nova-3") # Apply other options )See our API reference for more info.
Transcribe audio from a file.
fromdeepgramimportPrerecordedOptionsresponse=deepgram.listen.rest.v("1").transcribe_file( source=open("path/to/your/audio.wav", "rb"), options=PrerecordedOptions(model="nova-3") # Apply other options )See our API reference for more info.
Transcribe audio from a URL.
fromdeepgramimportPrerecordedOptionsresponse=deepgram.listen.rest.v("1").transcribe_url_async( source={"url": "https://dpgr.am/spacewalk.wav"}, callback_url="https://your-callback-url.com/webhook", options=PrerecordedOptions(model="nova-3") # Apply other options )See our API reference for more info.
Transcribe audio from a file.
fromdeepgramimportPrerecordedOptionsresponse=deepgram.listen.rest.v("1").transcribe_file_async( source=open("path/to/your/audio.wav", "rb"), callback_url="https://your-callback-url.com/webhook", options=PrerecordedOptions(model="nova-3") # Apply other options )See our API reference for more info.
Transcribe streaming audio.
fromdeepgramimportLiveOptions, LiveTranscriptionEvents# Create a websocket connectionconnection=deepgram.listen.websocket.v("1") # Handle transcription events@connection.on(LiveTranscriptionEvents.Transcript)defhandle_transcript(result): print(result.channel.alternatives[0].transcript) # Start connection with streaming optionsconnection.start(LiveOptions(model="nova-3", language="en-US")) # Send audio dataconnection.send(open("path/to/your/audio.wav", "rb").read()) # Close when doneconnection.finish()See our API reference for more info.
Transcribe audio to captions.
fromdeepgram_captionsimportDeepgramConverter, webvtttranscription=DeepgramConverter(dg_response) captions=webvtt(transcription)fromdeepgram_captionsimportDeepgramConverter, srttranscription=DeepgramConverter(dg_response) captions=srt(transcription)See our stand alone captions library for more information..
Configure a Voice Agent.
fromdeepgramimport ( SettingsOptions, Speak ) # Create websocket connectionconnection=deepgram.agent.websocket.v("1") # Configure agent settingsoptions=SettingsOptions() options.language="en"options.agent.think.provider.type="open_ai"options.agent.think.provider.model="gpt-4o-mini"options.agent.think.prompt="You are a helpful AI assistant."options.agent.listen.provider.type="deepgram"options.agent.listen.provider.model="nova-3"# Configure multiple TTS providers for automatic fallback.primary=Speak() primary.provider.type="deepgram"primary.provider.model="aura-2-zeus-en"fallback=Speak() fallback.provider.type="cartesia"fallback.provider.model="sonic-english"options.agent.speak= [primary, fallback] # Set Agent greetingoptions.greeting="Hello, I'm your AI assistant."# Start the connectionconnection.start(options) # Close the connectionconnection.finish()This example demonstrates:
- Setting up a WebSocket connection
- Configuring the agent with speech, language, and audio settings
- Handling various agent events (speech, transcripts, audio)
- Sending audio data and keeping the connection alive
For a complete implementation, you would need to:
- Add your audio input source (e.g., microphone)
- Implement audio playback for the agent's responses
- Handle any function calls if your agent uses them
- Add proper error handling and connection management
See our API reference for more info.
Convert text into speech using the REST API.
fromdeepgramimportSpeakOptions# Configure speech optionsoptions=SpeakOptions(model="aura-2-thalia-en") # Convert text to speech and save to fileresponse=deepgram.speak.rest.v("1").save( "output.mp3",{"text": "Hello world!"}, options )See our API reference for more info.
Convert streaming text into speech using a Websocket.
fromdeepgramimport ( SpeakWSOptions, SpeakWebSocketEvents ) # Create websocket connectionconnection=deepgram.speak.websocket.v("1") # Handle audio data@connection.on(SpeakWebSocketEvents.AudioData)# Configure streaming optionsoptions=SpeakWSOptions( model="aura-2-thalia-en", encoding="linear16", sample_rate=16000 ) # Start connection and send textconnection.start(options) connection.send_text("Hello, this is a text to speech example.") connection.flush() connection.wait_for_complete() # Close when doneconnection.finish()See our API reference for more info.
Analyze text.
fromdeepgramimportReadOptions# Configure read optionsoptions=ReadOptions( model="nova-3", language="en" ) # Process text for intelligenceresponse=deepgram.read.rest.v("1").process( text="The quick brown fox jumps over the lazy dog.", options=options )See our API reference for more info.
The Deepgram Python SDK supports multiple authentication methods to provide flexibility and enhanced security for your applications.
The traditional method using your Deepgram API key:
fromdeepgramimportDeepgramClient# Direct API keyclient=DeepgramClient(api_key="YOUR_API_KEY") # Or using environment variable DEEPGRAM_API_KEYclient=DeepgramClient() # Auto-detects from environmentUse short-lived access tokens for enhanced security:
fromdeepgramimportDeepgramClient# Direct access tokenclient=DeepgramClient(access_token="YOUR_ACCESS_TOKEN") # Or using environment variable DEEPGRAM_ACCESS_TOKENclient=DeepgramClient() # Auto-detects from environmentWhen multiple credentials are provided, the SDK follows this priority order:
- Explicit
access_tokenparameter (highest priority) - Explicit
api_keyparameter DEEPGRAM_ACCESS_TOKENenvironment variableDEEPGRAM_API_KEYenvironment variable (lowest priority)
Set your credentials using environment variables:
# For API key authenticationexport DEEPGRAM_API_KEY="your-deepgram-api-key"# For bearer token authenticationexport DEEPGRAM_ACCESS_TOKEN="your-access-token"Switch between authentication methods at runtime:
fromdeepgramimportDeepgramClient, DeepgramClientOptions# Start with API keyconfig=DeepgramClientOptions(api_key="your-api-key") client=DeepgramClient(config=config) # Switch to access tokenclient._config.set_access_token("your-access-token") # Switch back to API keyclient._config.set_apikey("your-api-key")Here's a practical example of using API keys to obtain access tokens:
fromdeepgramimportDeepgramClient# Step 1: Create client with API keyapi_client=DeepgramClient(api_key="your-api-key") # Step 2: Get a short-lived access token (30-second TTL)response=api_client.auth.v("1").grant_token() access_token=response.access_token# Step 3: Create new client with Bearer tokenbearer_client=DeepgramClient(access_token=access_token) # Step 4: Use the Bearer client for API callstranscription=bearer_client.listen.rest.v("1").transcribe_url({"url": "https://dpgr.am/spacewalk.wav"} )- Enhanced Security: Short-lived tokens (30-second expiration) minimize risk
- OAuth 2.0 Compliance: Standard bearer token format
- Scope Limitation: Tokens can be scoped to specific permissions
- Audit Trail: Better tracking of token usage vs API keys
Retrieves the details of the current authentication token:
response=deepgram.manage.rest.v("1").get_token_details()Creates a temporary token with a 30-second TTL:
response=deepgram.auth.v("1").grant_token()See our API reference for more info.
Returns all projects accessible by the API key.
response=deepgram.manage.v("1").get_projects()See our API reference for more info.
Retrieves a specific project based on the provided project_id.
response=deepgram.manage.v("1").get_project(myProjectId)See our API reference for more info.
Update a project.
response=deepgram.manage.v("1").update_project(myProjectId, options)See our API reference for more info.
Delete a project.
response=deepgram.manage.v("1").delete_project(myProjectId)See our API reference for more info.
Retrieves all keys associated with the provided project_id.
response=deepgram.manage.v("1").get_keys(myProjectId)See our API reference for more info
Retrieves a specific key associated with the provided project_id.
response=deepgram.manage.v("1").get_key(myProjectId, myKeyId)See our API reference for more info
Creates an API key with the provided scopes.
response=deepgram.manage.v("1").create_key(myProjectId, options)See our API reference for more info
Deletes a specific key associated with the provided project_id.
response=deepgram.manage.v("1").delete_key(myProjectId, myKeyId)See our API reference for more info
Retrieves account objects for all of the accounts in the specified project_id.
response=deepgram.manage.v("1").get_members(myProjectId)See our API reference for more info.
Removes member account for specified member_id.
response=deepgram.manage.v("1").remove_member(myProjectId, MemberId)See our API reference for more info.
Retrieves scopes of the specified member in the specified project.
response=deepgram.manage.v("1").get_member_scopes(myProjectId, memberId)See our API reference for more info.
Updates the scope for the specified member in the specified project.
response=deepgram.manage.v("1").update_member_scope(myProjectId, memberId, options)See our API reference for more info.
Retrieves all invitations associated with the provided project_id.
response=deepgram.manage.v("1").get_invites(myProjectId)See our API reference for more info.
Sends an invitation to the provided email address.
response=deepgram.manage.v("1").send_invite(myProjectId, options)See our API reference for more info.
Removes the specified invitation from the project.
response=deepgram.manage.v("1").delete_invite(myProjectId, email)See our API reference for more info.
response=deepgram.manage.v("1").leave_project(myProjectId)See our API reference for more info.
Retrieves all requests associated with the provided project_id based on the provided options.
response=deepgram.manage.v("1").get_usage_requests(myProjectId)See our API reference for more info.
Retrieves a specific request associated with the provided project_id
response=deepgram.manage.v("1").get_usage_request(myProjectId, RequestId)See our API reference for more info.
Lists the features, models, tags, languages, and processing method used for requests in the specified project.
response=deepgram.manage.v("1").get_usage_fields(myProjectId)See our API reference for more info.
Deprecated Retrieves the usage for a specific project. Use Get Project Usage Breakdown for a more comprehensive usage summary.
response=deepgram.manage.v("1").get_usage_summary(myProjectId)See our API reference for more info.
Retrieves the list of balance info for the specified project.
response=deepgram.manage.v("1").get_balances(myProjectId)See our API reference for more info.
Retrieves the balance info for the specified project and balance_id.
response=deepgram.manage.v("1").get_balance(myProjectId)See our API reference for more info.
Retrieves all models available for a given project.
response=deepgram.manage.v("1").get_project_models(myProjectId)See our API reference for more info.
Retrieves details of a specific model.
response=deepgram.manage.v("1").get_project_model(myProjectId, ModelId)See our API reference for more info.
Lists sets of distribution credentials for the specified project.
response=deepgram.selfhosted.v("1").list_selfhosted_credentials(projectId)See our API reference for more info.
Returns a set of distribution credentials for the specified project.
response=deepgram.selfhosted.v("1").get_selfhosted_credentials(projectId, distributionCredentialsId)See our API reference for more info.
Creates a set of distribution credentials for the specified project.
response=deepgram.selfhosted.v("1").create_selfhosted_credentials(project_id, options)See our API reference for more info.
Deletes a set of distribution credentials for the specified project.
response=deepgram.selfhosted.v("1").delete_selfhosted_credentials(projectId, distributionCredentialId)See our API reference for more info.
To ensure your application remains stable and reliable, we recommend using version pinning in your project. This is a best practice in Python development that helps prevent unexpected changes. You can pin to a major version (like ==4.*) for a good balance of stability and updates, or to a specific version (like ==4.1.0) for maximum stability. We've included some helpful resources about version pinning and dependency management if you'd like to learn more. For a deeper understanding of how version numbers work, check outsemantic versioning.
In a requirements.txt file, you can pin to a specific version like this:
deepgram-sdk==4.1.0Or using pip:
pip install deepgram-sdk==4.1.0This SDK provides logging as a means to troubleshoot and debug issues encountered. By default, this SDK will enable Information level messages and higher (ie Warning, Error, etc) when you initialize the library as follows:
deepgram: DeepgramClient=DeepgramClient()To increase the logging output/verbosity for debug or troubleshooting purposes, you can set the DEBUG level but using this code:
config: DeepgramClientOptions=DeepgramClientOptions( verbose=logging.DEBUG, ) deepgram: DeepgramClient=DeepgramClient("", config)If you are looking to use, run, contribute or modify to the daily/unit tests, then you need to install the following dependencies:
pip install -r requirements-dev.txtThe daily tests invoke a series of checks against the actual/real API endpoint and save the results in the tests/response_data folder. This response data is updated nightly to reflect the latest response from the server. Running the daily tests does require a DEEPGRAM_API_KEY set in your environment variables.
To run the Daily Tests:
make daily-testThe unit tests invoke a series of checks against mock endpoints using the responses saved in tests/response_data from the daily tests. These tests are meant to simulate running against the endpoint without actually reaching out to the endpoint; running the unit tests does require a DEEPGRAM_API_KEY set in your environment variables, but you will not actually reach out to the server.
make unit-testWe follow semantic versioning (semver) to ensure a smooth upgrade experience. Within a major version (like 4.*), we will maintain backward compatibility so your code will continue to work without breaking changes. When we release a new major version (like moving from 3.* to 4.*), we may introduce breaking changes to improve the SDK. We'll always document these changes clearly in our release notes to help you upgrade smoothly.
Older SDK versions will receive Priority 1 (P1) bug support only. Security issues, both in our code and dependencies, are promptly addressed. Significant bugs without clear workarounds are also given priority attention.
Interested in contributing? We ❤️ pull requests!
To make sure our community is safe for all, be sure to review and agree to our Code of Conduct. Then see the Contribution guidelines for more information.
In order to develop new features for the SDK itself, you first need to uninstall any previous installation of the deepgram-sdk and then install/pip the dependencies contained in the requirements.txt then instruct python (via pip) to use the SDK by installing it locally.
From the root of the repo, that would entail:
pip uninstall deepgram-sdk pip install -r requirements.txt pip install -e .We love to hear from you so if you have questions, comments or find a bug in the project, let us know! You can either: