# Deepgram Python SDK
[](https://discord.gg/xWRaCDBtW4) [](https://github.com/deepgram/deepgram-python-sdk/actions/workflows/CI.yaml?branch=main) [](https://pypi.org/project/deepgram-sdk/)
[](./.github/CODE_OF_CONDUCT.md)
Official Python SDK for [Deepgram](https://www.deepgram.com/). Power your apps with world-class speech and Language AI models.
- [Documentation](#documentation)
- [Migrating from earlier versions](#migrating-from-earlier-versions)
- [V2 to V3](#v2-to-v3)
- [V3.\*\ to V4](#v3-to-v4)
- [Requirements](#requirements)
- [Installation](#installation)
- [Initialization](#initialization)
- [Getting an API Key](#getting-an-api-key)
- [Pre-Recorded (Synchronous)](#pre-recorded-synchronous)
- [Remote Files (Synchronous)](#remote-files-synchronous)
- [Local Files (Synchronous)](#local-files-synchronous)
- [Pre-Recorded (Asynchronous / Callbacks)](#pre-recorded-asynchronous--callbacks)
- [Remote Files (Asynchronous)](#remote-files-asynchronous)
- [Local Files (Asynchronous)](#local-files-asynchronous)
- [Streaming Audio](#streaming-audio)
- [Transcribing to Captions](#transcribing-to-captions)
- [Voice Agent](#voice-agent)
- [Text to Speech REST](#text-to-speech-rest)
- [Text to Speech Streaming](#text-to-speech-streaming)
- [Text Intelligence](#text-intelligence)
- [Authentication](#authentication)
- [Get Token Details](#get-token-details)
- [Grant Token](#grant-token)
- [Projects](#projects)
- [Get Projects](#get-projects)
- [Get Project](#get-project)
- [Update Project](#update-project)
- [Delete Project](#delete-project)
- [Keys](#keys)
- [List Keys](#list-keys)
- [Get Key](#get-key)
- [Create Key](#create-key)
- [Delete Key](#delete-key)
- [Members](#members)
- [Get Members](#get-members)
- [Remove Member](#remove-member)
- [Scopes](#scopes)
- [Get Member Scopes](#get-member-scopes)
- [Update Scope](#update-scope)
- [Invitations](#invitations)
- [List Invites](#list-invites)
- [Send Invite](#send-invite)
- [Delete Invite](#delete-invite)
- [Leave Project](#leave-project)
- [Usage](#usage)
- [Get All Requests](#get-all-requests)
- [Get Request](#get-request)
- [Summarize Usage](#summarize-usage)
- [Get Fields](#get-fields)
- [Billing](#billing)
- [Get All Balances](#get-all-balances)
- [Get Balance](#get-balance)
- [Models](#models)
- [Get All Project Models](#get-all-project-models)
- [Get Model](#get-model)
- [On-Prem APIs](#on-prem-apis)
- [List On-Prem credentials](#list-on-prem-credentials)
- [Get On-Prem credentials](#get-on-prem-credentials)
- [Create On-Prem credentials](#create-on-prem-credentials)
- [Delete On-Prem credentials](#delete-on-prem-credentials)
- [Logging](#logging)
- [Backwards Compatibility](#backwards-compatibility)
- [Development and Contributing](#development-and-contributing)
- [Getting Help](#getting-help)
## Documentation
You can learn more about the Deepgram API at [developers.deepgram.com](https://developers.deepgram.com/docs).
## Migrating from earlier versions
### V2 to V3
We have published [a migration guide on our docs](https://developers.deepgram.com/sdks/python-sdk/v2-to-v3-migration), showing how to move from v2 to v3.
### V3.\* to V4
The Voice Agent interfaces have been updated to use the new Voice Agent V1 API. Please refer to our [Documentation](https://developers.deepgram.com/docs/voice-agent-v1-migration) on Migration to new V1 Agent API.
## Requirements
[Python](https://www.python.org/downloads/) (version ^3.10)
## Installation
To install the latest version available:
```sh
pip install deepgram-sdk
```
## Initialization
All of the examples below will require `DeepgramClient`.
```python
from deepgram import DeepgramClient
# Initialize the client
deepgram = DeepgramClient("YOUR_API_KEY") # Replace with your API key
```
### Getting an API Key
🔑 To access the Deepgram API you will need a [free Deepgram API Key](https://console.deepgram.com/signup?jump=keys).
## Pre-Recorded (Synchronous)
### Remote Files (Synchronous)
Transcribe audio from a URL.
```python
from deepgram import PrerecordedOptions
response = 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](https://developers.deepgram.com/reference/speech-to-text-api/listen).
### Local Files (Synchronous)
Transcribe audio from a file.
```python
from deepgram import PrerecordedOptions
response = 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](https://developers.deepgram.com/reference/speech-to-text-api/listen).
## Pre-Recorded (Asynchronous / Callbacks)
### Remote Files (Asynchronous)
Transcribe audio from a URL.
```python
from deepgram import PrerecordedOptions
response = 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](https://developers.deepgram.com/reference/speech-to-text-api/listen).
### Local Files (Asynchronous)
Transcribe audio from a file.
```python
from deepgram import PrerecordedOptions
response = 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](https://developers.deepgram.com/reference/speech-to-text-api/listen).
## Streaming Audio
Transcribe streaming audio.
```python
from deepgram import LiveOptions, LiveTranscriptionEvents
# Create a websocket connection
connection = deepgram.listen.websocket.v("1")
# Handle transcription events
@connection.on(LiveTranscriptionEvents.Transcript)
def handle_transcript(result):
print(result.channel.alternatives[0].transcript)
# Start connection with streaming options
connection.start(LiveOptions(model="nova-3", language="en-US"))
# Send audio data
connection.send(open("path/to/your/audio.wav", "rb").read())
# Close when done
connection.finish()
```
[See our API reference for more info](https://developers.deepgram.com/reference/streaming-api).
## Transcribing to Captions
Transcribe audio to captions.
### WebVTT
```python
from deepgram_captions import DeepgramConverter, webvtt
transcription = DeepgramConverter(dg_response)
captions = webvtt(transcription)
```
### SRT
```python
from deepgram_captions import DeepgramConverter, srt
transcription = DeepgramConverter(dg_response)
captions = srt(transcription)
```
[See our stand alone captions library for more information.](https://github.com/deepgram/deepgram-python-captions).
## Voice Agent
Configure a Voice Agent.
```python
from deepgram import (
SettingsOptions,
Speak
)
# Create websocket connection
connection = deepgram.agent.websocket.v("1")
# Configure agent settings
options = 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 greeting
options.greeting = "Hello, I'm your AI assistant."
# Start the connection
connection.start(options)
# Close the connection
connection.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:
1. Add your audio input source (e.g., microphone)
2. Implement audio playback for the agent's responses
3. Handle any function calls if your agent uses them
4. Add proper error handling and connection management
[See our API reference for more info](https://developers.deepgram.com/reference/voice-agent-api/agent).
## Text to Speech REST
Convert text into speech using the REST API.
```python
from deepgram import SpeakOptions
# Configure speech options
options = SpeakOptions(model="aura-2-thalia-en")
# Convert text to speech and save to file
response = deepgram.speak.rest.v("1").save(
"output.mp3",
{"text": "Hello world!"},
options
)
```
[See our API reference for more info](https://developers.deepgram.com/reference/text-to-speech-api/speak).
## Text to Speech Streaming
Convert streaming text into speech using a Websocket.
```python
from deepgram import (
SpeakWSOptions,
SpeakWebSocketEvents
)
# Create websocket connection
connection = deepgram.speak.websocket.v("1")
# Handle audio data
@connection.on(SpeakWebSocketEvents.AudioData)
# Configure streaming options
options = SpeakWSOptions(
model="aura-2-thalia-en",
encoding="linear16",
sample_rate=16000
)
# Start connection and send text
connection.start(options)
connection.send_text("Hello, this is a text to speech example.")
connection.flush()
connection.wait_for_complete()
# Close when done
connection.finish()
```
[See our API reference for more info](https://developers.deepgram.com/reference/text-to-speech-api/speak).
## Text Intelligence
Analyze text.
```python
from deepgram import ReadOptions
# Configure read options
options = ReadOptions(
model="nova-3",
language="en"
)
# Process text for intelligence
response = 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](https://developers.deepgram.com/reference/text-intelligence-api/text-read).
## Authentication
The Deepgram Python SDK supports multiple authentication methods to provide flexibility and enhanced security for your applications.
### Authentication Methods
#### API Key Authentication (Traditional)
The traditional method using your Deepgram API key:
```python
from deepgram import DeepgramClient
# Direct API key
client = DeepgramClient(api_key="YOUR_API_KEY")
# Or using environment variable DEEPGRAM_API_KEY
client = DeepgramClient() # Auto-detects from environment
```
#### Bearer Token Authentication (OAuth 2.0)
Use short-lived access tokens for enhanced security:
```python
from deepgram import DeepgramClient
# Direct access token
client = DeepgramClient(access_token="YOUR_ACCESS_TOKEN")
# Or using environment variable DEEPGRAM_ACCESS_TOKEN
client = DeepgramClient() # Auto-detects from environment
```
### Authentication Priority
When multiple credentials are provided, the SDK follows this priority order:
1. **Explicit `access_token` parameter** (highest priority)
2. **Explicit `api_key` parameter**
3. **`DEEPGRAM_ACCESS_TOKEN` environment variable**
4. **`DEEPGRAM_API_KEY` environment variable** (lowest priority)
### Environment Variables
Set your credentials using environment variables:
```bash
# For API key authentication
export DEEPGRAM_API_KEY="your-deepgram-api-key"
# For bearer token authentication
export DEEPGRAM_ACCESS_TOKEN="your-access-token"
```
### Dynamic Authentication Switching
Switch between authentication methods at runtime:
```python
from deepgram import DeepgramClient, DeepgramClientOptions
# Start with API key
config = DeepgramClientOptions(api_key="your-api-key")
client = DeepgramClient(config=config)
# Switch to access token
client._config.set_access_token("your-access-token")
# Switch back to API key
client._config.set_apikey("your-api-key")
```
### Complete Bearer Token Workflow
Here's a practical example of using API keys to obtain access tokens:
```python
from deepgram import DeepgramClient
# Step 1: Create client with API key
api_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 token
bearer_client = DeepgramClient(access_token=access_token)
# Step 4: Use the Bearer client for API calls
transcription = bearer_client.listen.rest.v("1").transcribe_url(
{"url": "https://dpgr.am/spacewalk.wav"}
)
```
### Benefits of Bearer Token Authentication
- **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
### Authentication Management
#### Get Token Details
Retrieves the details of the current authentication token:
```python
response = deepgram.manage.rest.v("1").get_token_details()
```
#### Grant Token
Creates a temporary token with a 30-second TTL:
```python
response = deepgram.auth.v("1").grant_token()
```
[See our API reference for more info](https://developers.deepgram.com/reference/token-based-auth-api/grant-token).
## Projects
### Get Projects
Returns all projects accessible by the API key.
```python
response = deepgram.manage.v("1").get_projects()
```
[See our API reference for more info](https://developers.deepgram.com/reference/management-api/projects/list).
### Get Project
Retrieves a specific project based on the provided project_id.
```python
response = deepgram.manage.v("1").get_project(myProjectId)
```
[See our API reference for more info](https://developers.deepgram.com/reference/management-api/projects/get).
### Update Project
Update a project.
```python
response = deepgram.manage.v("1").update_project(myProjectId, options)
```
[See our API reference for more info](https://developers.deepgram.com/reference/management-api/projects/update).
### Delete Project
Delete a project.
```python
response = deepgram.manage.v("1").delete_project(myProjectId)
```
[See our API reference for more info](https://developers.deepgram.com/reference/management-api/projects/delete).
## Keys
### List Keys
Retrieves all keys associated with the provided project_id.
```python
response = deepgram.manage.v("1").get_keys(myProjectId)
```
[See our API reference for more info](https://developers.deepgram.com/reference/management-api/keys/list)
### Get Key
Retrieves a specific key associated with the provided project_id.
```python
response = deepgram.manage.v("1").get_key(myProjectId, myKeyId)
```
[See our API reference for more info](https://developers.deepgram.com/reference/management-api/keys/get)
### Create Key
Creates an API key with the provided scopes.
```python
response = deepgram.manage.v("1").create_key(myProjectId, options)
```
[See our API reference for more info](https://developers.deepgram.com/reference/management-api/keys/create)
### Delete Key
Deletes a specific key associated with the provided project_id.
```python
response = deepgram.manage.v("1").delete_key(myProjectId, myKeyId)
```
[See our API reference for more info](https://developers.deepgram.com/reference/management-api/keys/delete)
## Members
### Get Members
Retrieves account objects for all of the accounts in the specified project_id.
```python
response = deepgram.manage.v("1").get_members(myProjectId)
```
[See our API reference for more info](https://developers.deepgram.com/reference/management-api/members/list).
### Remove Member
Removes member account for specified member_id.
```python
response = deepgram.manage.v("1").remove_member(myProjectId, MemberId)
```
[See our API reference for more info](https://developers.deepgram.com/reference/management-api/members/delete).
## Scopes
### Get Member Scopes
Retrieves scopes of the specified member in the specified project.
```python
response = deepgram.manage.v("1").get_member_scopes(myProjectId, memberId)
```
[See our API reference for more info](https://developers.deepgram.com/reference/management-api/scopes/list).
### Update Scope
Updates the scope for the specified member in the specified project.
```python
response = deepgram.manage.v("1").update_member_scope(myProjectId, memberId, options)
```
[See our API reference for more info](https://developers.deepgram.com/reference/management-api/scopes/update).
## Invitations
### List Invites
Retrieves all invitations associated with the provided project_id.
```python
response = deepgram.manage.v("1").get_invites(myProjectId)
```
[See our API reference for more info](https://developers.deepgram.com/reference/management-api/invitations/list).
### Send Invite
Sends an invitation to the provided email address.
```python
response = deepgram.manage.v("1").send_invite(myProjectId, options)
```
[See our API reference for more info](https://developers.deepgram.com/reference/management-api/invitations/create).
### Delete Invite
Removes the specified invitation from the project.
```python
response = deepgram.manage.v("1").delete_invite(myProjectId, email)
```
[See our API reference for more info](https://developers.deepgram.com/reference/management-api/invitations/delete).
### Leave Project
```python
response = deepgram.manage.v("1").leave_project(myProjectId)
```
[See our API reference for more info](https://developers.deepgram.com/reference/management-api/invitations/leave).
## Usage
### Get All Requests
Retrieves all requests associated with the provided project_id based on the provided options.
```python
response = deepgram.manage.v("1").get_usage_requests(myProjectId)
```
[See our API reference for more info](https://developers.deepgram.com/reference/management-api/usage/list-requests).
### Get Request
Retrieves a specific request associated with the provided project_id
```python
response = deepgram.manage.v("1").get_usage_request(myProjectId, RequestId)
```
[See our API reference for more info](https://developers.deepgram.com/reference/management-api/usage/get-request).
### Get Fields
Lists the features, models, tags, languages, and processing method used for requests in the specified project.
```python
response = deepgram.manage.v("1").get_usage_fields(myProjectId)
```
[See our API reference for more info](https://developers.deepgram.com/reference/management-api/usage/list-fields).
### Summarize Usage
`Deprecated` Retrieves the usage for a specific project. Use Get Project Usage Breakdown for a more comprehensive usage summary.
```python
response = deepgram.manage.v("1").get_usage_summary(myProjectId)
```
[See our API reference for more info](https://developers.deepgram.com/reference/management-api/usage/get).
## Billing
### Get All Balances
Retrieves the list of balance info for the specified project.
```python
response = deepgram.manage.v("1").get_balances(myProjectId)
```
[See our API reference for more info](https://developers.deepgram.com/reference/management-api/balances/list).
### Get Balance
Retrieves the balance info for the specified project and balance_id.
```python
response = deepgram.manage.v("1").get_balance(myProjectId)
```
[See our API reference for more info](https://developers.deepgram.com/reference/management-api/balances/get).
## Models
### Get All Project Models
Retrieves all models available for a given project.
```python
response = deepgram.manage.v("1").get_project_models(myProjectId)
```
[See our API reference for more info](https://developers.deepgram.com/reference/management-api/projects/list-models).
### Get Model
Retrieves details of a specific model.
```python
response = deepgram.manage.v("1").get_project_model(myProjectId, ModelId)
```
[See our API reference for more info](https://developers.deepgram.com/reference/management-api/projects/get-model).
## On-Prem APIs
### List On-Prem credentials
Lists sets of distribution credentials for the specified project.
```python
response = deepgram.selfhosted.v("1").list_selfhosted_credentials(projectId)
```
[See our API reference for more info](https://developers.deepgram.com/reference/self-hosted-api/list-credentials).
### Get On-Prem credentials
Returns a set of distribution credentials for the specified project.
```python
response = deepgram.selfhosted.v("1").get_selfhosted_credentials(projectId, distributionCredentialsId)
```
[See our API reference for more info](https://developers.deepgram.com/reference/self-hosted-api/get-credentials).
### Create On-Prem credentials
Creates a set of distribution credentials for the specified project.
```python
response = deepgram.selfhosted.v("1").create_selfhosted_credentials(project_id, options)
```
[See our API reference for more info](https://developers.deepgram.com/reference/self-hosted-api/create-credentials).
### Delete On-Prem credentials
Deletes a set of distribution credentials for the specified project.
```python
response = deepgram.selfhosted.v("1").delete_selfhosted_credentials(projectId, distributionCredentialId)
```
[See our API reference for more info](https://developers.deepgram.com/reference/self-hosted-api/delete-credentials).
## Pinning Versions
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](https://discuss.python.org/t/how-to-pin-a-package-to-a-specific-major-version-or-lower/17077) and [dependency management](https://www.easypost.com/dependency-pinning-guide) if you'd like to learn more. For a deeper understanding of how version numbers work, check out[semantic versioning](https://semver.org/).
In a `requirements.txt` file, you can pin to a specific version like this:
```sh
deepgram-sdk==4.1.0
```
Or using pip:
```sh
pip install deepgram-sdk==4.1.0
```
## Logging
This 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:
```python
deepgram: DeepgramClient = DeepgramClient()
```
To increase the logging output/verbosity for debug or troubleshooting purposes, you can set the `DEBUG` level but using this code:
```python
config: DeepgramClientOptions = DeepgramClientOptions(
verbose=logging.DEBUG,
)
deepgram: DeepgramClient = DeepgramClient("", config)
```
## Testing
### Daily and Unit Tests
If you are looking to use, run, contribute or modify to the daily/unit tests, then you need to install the following dependencies:
```bash
pip install -r requirements-dev.txt
```
### Daily Tests
The 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:
```bash
make daily-test
```
#### Unit Tests
The 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.
```bash
make unit-test
```
## Backwards Compatibility
We 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.
## Development and Contributing
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](CODE_OF_CONDUCT.md). Then see the
[Contribution](CONTRIBUTING.md) 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:
```bash
pip uninstall deepgram-sdk
pip install -r requirements.txt
pip install -e .
```
## Getting Help
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:
- [Open an issue in this repository](https://github.com/deepgram/deepgram-python-sdk/issues/new)
- [Join the Deepgram Github Discussions Community](https://github.com/orgs/deepgram/discussions)
- [Join the Deepgram Discord Community](https://discord.gg/xWRaCDBtW4)
Raw data
{
"_id": null,
"home_page": "https://github.com/deepgram/deepgram-python-sdk",
"name": "deepgram-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "deepgram, deepgram speech-to-text",
"author": "Deepgram",
"author_email": "devrel@deepgram.com",
"download_url": "https://files.pythonhosted.org/packages/17/c7/3c5918c2c74e3d56cf3d738aa174bc688c73069dc9682fc1bfaeb2058cc6/deepgram_sdk-4.7.0.tar.gz",
"platform": null,
"description": "# Deepgram Python SDK\n\n[](https://discord.gg/xWRaCDBtW4) [](https://github.com/deepgram/deepgram-python-sdk/actions/workflows/CI.yaml?branch=main) [](https://pypi.org/project/deepgram-sdk/)\n[](./.github/CODE_OF_CONDUCT.md)\n\nOfficial Python SDK for [Deepgram](https://www.deepgram.com/). Power your apps with world-class speech and Language AI models.\n\n- [Documentation](#documentation)\n- [Migrating from earlier versions](#migrating-from-earlier-versions)\n - [V2 to V3](#v2-to-v3)\n - [V3.\\*\\ to V4](#v3-to-v4)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Initialization](#initialization)\n - [Getting an API Key](#getting-an-api-key)\n- [Pre-Recorded (Synchronous)](#pre-recorded-synchronous)\n - [Remote Files (Synchronous)](#remote-files-synchronous)\n - [Local Files (Synchronous)](#local-files-synchronous)\n- [Pre-Recorded (Asynchronous / Callbacks)](#pre-recorded-asynchronous--callbacks)\n - [Remote Files (Asynchronous)](#remote-files-asynchronous)\n - [Local Files (Asynchronous)](#local-files-asynchronous)\n- [Streaming Audio](#streaming-audio)\n- [Transcribing to Captions](#transcribing-to-captions)\n- [Voice Agent](#voice-agent)\n- [Text to Speech REST](#text-to-speech-rest)\n- [Text to Speech Streaming](#text-to-speech-streaming)\n- [Text Intelligence](#text-intelligence)\n- [Authentication](#authentication)\n - [Get Token Details](#get-token-details)\n - [Grant Token](#grant-token)\n- [Projects](#projects)\n - [Get Projects](#get-projects)\n - [Get Project](#get-project)\n - [Update Project](#update-project)\n - [Delete Project](#delete-project)\n- [Keys](#keys)\n - [List Keys](#list-keys)\n - [Get Key](#get-key)\n - [Create Key](#create-key)\n - [Delete Key](#delete-key)\n- [Members](#members)\n - [Get Members](#get-members)\n - [Remove Member](#remove-member)\n- [Scopes](#scopes)\n - [Get Member Scopes](#get-member-scopes)\n - [Update Scope](#update-scope)\n- [Invitations](#invitations)\n - [List Invites](#list-invites)\n - [Send Invite](#send-invite)\n - [Delete Invite](#delete-invite)\n - [Leave Project](#leave-project)\n- [Usage](#usage)\n - [Get All Requests](#get-all-requests)\n - [Get Request](#get-request)\n - [Summarize Usage](#summarize-usage)\n - [Get Fields](#get-fields)\n- [Billing](#billing)\n - [Get All Balances](#get-all-balances)\n - [Get Balance](#get-balance)\n- [Models](#models)\n - [Get All Project Models](#get-all-project-models)\n - [Get Model](#get-model)\n- [On-Prem APIs](#on-prem-apis)\n - [List On-Prem credentials](#list-on-prem-credentials)\n - [Get On-Prem credentials](#get-on-prem-credentials)\n - [Create On-Prem credentials](#create-on-prem-credentials)\n - [Delete On-Prem credentials](#delete-on-prem-credentials)\n- [Logging](#logging)\n- [Backwards Compatibility](#backwards-compatibility)\n- [Development and Contributing](#development-and-contributing)\n- [Getting Help](#getting-help)\n\n## Documentation\n\nYou can learn more about the Deepgram API at [developers.deepgram.com](https://developers.deepgram.com/docs).\n\n## Migrating from earlier versions\n\n### V2 to V3\n\nWe have published [a migration guide on our docs](https://developers.deepgram.com/sdks/python-sdk/v2-to-v3-migration), showing how to move from v2 to v3.\n\n### V3.\\* to V4\n\nThe Voice Agent interfaces have been updated to use the new Voice Agent V1 API. Please refer to our [Documentation](https://developers.deepgram.com/docs/voice-agent-v1-migration) on Migration to new V1 Agent API.\n\n## Requirements\n\n[Python](https://www.python.org/downloads/) (version ^3.10)\n\n## Installation\n\nTo install the latest version available:\n\n```sh\npip install deepgram-sdk\n```\n\n## Initialization\n\nAll of the examples below will require `DeepgramClient`.\n\n```python\nfrom deepgram import DeepgramClient\n\n# Initialize the client\ndeepgram = DeepgramClient(\"YOUR_API_KEY\") # Replace with your API key\n```\n\n### Getting an API Key\n\n\ud83d\udd11 To access the Deepgram API you will need a [free Deepgram API Key](https://console.deepgram.com/signup?jump=keys).\n\n## Pre-Recorded (Synchronous)\n\n### Remote Files (Synchronous)\n\nTranscribe audio from a URL.\n\n```python\n\nfrom deepgram import PrerecordedOptions\n\nresponse = deepgram.listen.rest.v(\"1\").transcribe_url(\n source={\"url\": \"https://dpgr.am/spacewalk.wav\"},\n options=PrerecordedOptions(model=\"nova-3\") # Apply other options\n)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/speech-to-text-api/listen).\n\n### Local Files (Synchronous)\n\nTranscribe audio from a file.\n\n```python\nfrom deepgram import PrerecordedOptions\n\nresponse = deepgram.listen.rest.v(\"1\").transcribe_file(\n source=open(\"path/to/your/audio.wav\", \"rb\"),\n options=PrerecordedOptions(model=\"nova-3\") # Apply other options\n)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/speech-to-text-api/listen).\n\n## Pre-Recorded (Asynchronous / Callbacks)\n\n### Remote Files (Asynchronous)\n\nTranscribe audio from a URL.\n\n```python\nfrom deepgram import PrerecordedOptions\n\nresponse = deepgram.listen.rest.v(\"1\").transcribe_url_async(\n source={\"url\": \"https://dpgr.am/spacewalk.wav\"},\n callback_url=\"https://your-callback-url.com/webhook\",\n options=PrerecordedOptions(model=\"nova-3\") # Apply other options\n)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/speech-to-text-api/listen).\n\n### Local Files (Asynchronous)\n\nTranscribe audio from a file.\n\n```python\nfrom deepgram import PrerecordedOptions\n\nresponse = deepgram.listen.rest.v(\"1\").transcribe_file_async(\n source=open(\"path/to/your/audio.wav\", \"rb\"),\n callback_url=\"https://your-callback-url.com/webhook\",\n options=PrerecordedOptions(model=\"nova-3\") # Apply other options\n)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/speech-to-text-api/listen).\n\n## Streaming Audio\n\nTranscribe streaming audio.\n\n```python\nfrom deepgram import LiveOptions, LiveTranscriptionEvents\n\n# Create a websocket connection\nconnection = deepgram.listen.websocket.v(\"1\")\n\n# Handle transcription events\n@connection.on(LiveTranscriptionEvents.Transcript)\ndef handle_transcript(result):\n print(result.channel.alternatives[0].transcript)\n\n# Start connection with streaming options\nconnection.start(LiveOptions(model=\"nova-3\", language=\"en-US\"))\n\n# Send audio data\nconnection.send(open(\"path/to/your/audio.wav\", \"rb\").read())\n\n# Close when done\nconnection.finish()\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/streaming-api).\n\n## Transcribing to Captions\n\nTranscribe audio to captions.\n\n### WebVTT\n\n```python\nfrom deepgram_captions import DeepgramConverter, webvtt\n\ntranscription = DeepgramConverter(dg_response)\ncaptions = webvtt(transcription)\n```\n\n### SRT\n\n```python\nfrom deepgram_captions import DeepgramConverter, srt\n\ntranscription = DeepgramConverter(dg_response)\ncaptions = srt(transcription)\n```\n\n[See our stand alone captions library for more information.](https://github.com/deepgram/deepgram-python-captions).\n\n## Voice Agent\n\nConfigure a Voice Agent.\n\n```python\nfrom deepgram import (\n SettingsOptions,\n Speak\n)\n\n# Create websocket connection\nconnection = deepgram.agent.websocket.v(\"1\")\n\n# Configure agent settings\noptions = SettingsOptions()\noptions.language = \"en\"\noptions.agent.think.provider.type = \"open_ai\"\noptions.agent.think.provider.model = \"gpt-4o-mini\"\noptions.agent.think.prompt = \"You are a helpful AI assistant.\"\noptions.agent.listen.provider.type = \"deepgram\"\noptions.agent.listen.provider.model = \"nova-3\"\n\n# Configure multiple TTS providers for automatic fallback.\nprimary = Speak()\nprimary.provider.type = \"deepgram\"\nprimary.provider.model = \"aura-2-zeus-en\"\n\nfallback = Speak()\nfallback.provider.type = \"cartesia\"\nfallback.provider.model = \"sonic-english\"\n\noptions.agent.speak = [primary, fallback]\n# Set Agent greeting\noptions.greeting = \"Hello, I'm your AI assistant.\"\n\n# Start the connection\nconnection.start(options)\n\n# Close the connection\nconnection.finish()\n```\n\nThis example demonstrates:\n\n- Setting up a WebSocket connection\n- Configuring the agent with speech, language, and audio settings\n- Handling various agent events (speech, transcripts, audio)\n- Sending audio data and keeping the connection alive\n\nFor a complete implementation, you would need to:\n\n1. Add your audio input source (e.g., microphone)\n2. Implement audio playback for the agent's responses\n3. Handle any function calls if your agent uses them\n4. Add proper error handling and connection management\n\n[See our API reference for more info](https://developers.deepgram.com/reference/voice-agent-api/agent).\n\n## Text to Speech REST\n\nConvert text into speech using the REST API.\n\n```python\nfrom deepgram import SpeakOptions\n\n# Configure speech options\noptions = SpeakOptions(model=\"aura-2-thalia-en\")\n\n# Convert text to speech and save to file\nresponse = deepgram.speak.rest.v(\"1\").save(\n \"output.mp3\",\n {\"text\": \"Hello world!\"},\n options\n)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/text-to-speech-api/speak).\n\n## Text to Speech Streaming\n\nConvert streaming text into speech using a Websocket.\n\n```python\nfrom deepgram import (\n SpeakWSOptions,\n SpeakWebSocketEvents\n)\n\n# Create websocket connection\nconnection = deepgram.speak.websocket.v(\"1\")\n\n# Handle audio data\n@connection.on(SpeakWebSocketEvents.AudioData)\n\n# Configure streaming options\noptions = SpeakWSOptions(\n model=\"aura-2-thalia-en\",\n encoding=\"linear16\",\n sample_rate=16000\n)\n\n# Start connection and send text\nconnection.start(options)\nconnection.send_text(\"Hello, this is a text to speech example.\")\nconnection.flush()\nconnection.wait_for_complete()\n\n# Close when done\nconnection.finish()\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/text-to-speech-api/speak).\n\n## Text Intelligence\n\nAnalyze text.\n\n```python\nfrom deepgram import ReadOptions\n\n# Configure read options\noptions = ReadOptions(\n model=\"nova-3\",\n language=\"en\"\n)\n\n# Process text for intelligence\nresponse = deepgram.read.rest.v(\"1\").process(\n text=\"The quick brown fox jumps over the lazy dog.\",\n options=options\n)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/text-intelligence-api/text-read).\n\n## Authentication\n\nThe Deepgram Python SDK supports multiple authentication methods to provide flexibility and enhanced security for your applications.\n\n### Authentication Methods\n\n#### API Key Authentication (Traditional)\n\nThe traditional method using your Deepgram API key:\n\n```python\nfrom deepgram import DeepgramClient\n\n# Direct API key\nclient = DeepgramClient(api_key=\"YOUR_API_KEY\")\n\n# Or using environment variable DEEPGRAM_API_KEY\nclient = DeepgramClient() # Auto-detects from environment\n```\n\n#### Bearer Token Authentication (OAuth 2.0)\n\nUse short-lived access tokens for enhanced security:\n\n```python\nfrom deepgram import DeepgramClient\n\n# Direct access token\nclient = DeepgramClient(access_token=\"YOUR_ACCESS_TOKEN\")\n\n# Or using environment variable DEEPGRAM_ACCESS_TOKEN\nclient = DeepgramClient() # Auto-detects from environment\n```\n\n### Authentication Priority\n\nWhen multiple credentials are provided, the SDK follows this priority order:\n\n1. **Explicit `access_token` parameter** (highest priority)\n2. **Explicit `api_key` parameter**\n3. **`DEEPGRAM_ACCESS_TOKEN` environment variable**\n4. **`DEEPGRAM_API_KEY` environment variable** (lowest priority)\n\n### Environment Variables\n\nSet your credentials using environment variables:\n\n```bash\n# For API key authentication\nexport DEEPGRAM_API_KEY=\"your-deepgram-api-key\"\n\n# For bearer token authentication\nexport DEEPGRAM_ACCESS_TOKEN=\"your-access-token\"\n```\n\n### Dynamic Authentication Switching\n\nSwitch between authentication methods at runtime:\n\n```python\nfrom deepgram import DeepgramClient, DeepgramClientOptions\n\n# Start with API key\nconfig = DeepgramClientOptions(api_key=\"your-api-key\")\nclient = DeepgramClient(config=config)\n\n# Switch to access token\nclient._config.set_access_token(\"your-access-token\")\n\n# Switch back to API key\nclient._config.set_apikey(\"your-api-key\")\n```\n\n### Complete Bearer Token Workflow\n\nHere's a practical example of using API keys to obtain access tokens:\n\n```python\nfrom deepgram import DeepgramClient\n\n# Step 1: Create client with API key\napi_client = DeepgramClient(api_key=\"your-api-key\")\n\n# Step 2: Get a short-lived access token (30-second TTL)\nresponse = api_client.auth.v(\"1\").grant_token()\naccess_token = response.access_token\n\n# Step 3: Create new client with Bearer token\nbearer_client = DeepgramClient(access_token=access_token)\n\n# Step 4: Use the Bearer client for API calls\ntranscription = bearer_client.listen.rest.v(\"1\").transcribe_url(\n {\"url\": \"https://dpgr.am/spacewalk.wav\"}\n)\n```\n\n### Benefits of Bearer Token Authentication\n\n- **Enhanced Security**: Short-lived tokens (30-second expiration) minimize risk\n- **OAuth 2.0 Compliance**: Standard bearer token format\n- **Scope Limitation**: Tokens can be scoped to specific permissions\n- **Audit Trail**: Better tracking of token usage vs API keys\n\n### Authentication Management\n\n#### Get Token Details\n\nRetrieves the details of the current authentication token:\n\n```python\nresponse = deepgram.manage.rest.v(\"1\").get_token_details()\n```\n\n#### Grant Token\n\nCreates a temporary token with a 30-second TTL:\n\n```python\nresponse = deepgram.auth.v(\"1\").grant_token()\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/token-based-auth-api/grant-token).\n\n## Projects\n\n### Get Projects\n\nReturns all projects accessible by the API key.\n\n```python\nresponse = deepgram.manage.v(\"1\").get_projects()\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/management-api/projects/list).\n\n### Get Project\n\nRetrieves a specific project based on the provided project_id.\n\n```python\nresponse = deepgram.manage.v(\"1\").get_project(myProjectId)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/management-api/projects/get).\n\n### Update Project\n\nUpdate a project.\n\n```python\nresponse = deepgram.manage.v(\"1\").update_project(myProjectId, options)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/management-api/projects/update).\n\n### Delete Project\n\nDelete a project.\n\n```python\nresponse = deepgram.manage.v(\"1\").delete_project(myProjectId)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/management-api/projects/delete).\n\n## Keys\n\n### List Keys\n\nRetrieves all keys associated with the provided project_id.\n\n```python\nresponse = deepgram.manage.v(\"1\").get_keys(myProjectId)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/management-api/keys/list)\n\n### Get Key\n\nRetrieves a specific key associated with the provided project_id.\n\n```python\nresponse = deepgram.manage.v(\"1\").get_key(myProjectId, myKeyId)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/management-api/keys/get)\n\n### Create Key\n\nCreates an API key with the provided scopes.\n\n```python\n response = deepgram.manage.v(\"1\").create_key(myProjectId, options)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/management-api/keys/create)\n\n### Delete Key\n\nDeletes a specific key associated with the provided project_id.\n\n```python\nresponse = deepgram.manage.v(\"1\").delete_key(myProjectId, myKeyId)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/management-api/keys/delete)\n\n## Members\n\n### Get Members\n\nRetrieves account objects for all of the accounts in the specified project_id.\n\n```python\nresponse = deepgram.manage.v(\"1\").get_members(myProjectId)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/management-api/members/list).\n\n### Remove Member\n\nRemoves member account for specified member_id.\n\n```python\nresponse = deepgram.manage.v(\"1\").remove_member(myProjectId, MemberId)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/management-api/members/delete).\n\n## Scopes\n\n### Get Member Scopes\n\nRetrieves scopes of the specified member in the specified project.\n\n```python\nresponse = deepgram.manage.v(\"1\").get_member_scopes(myProjectId, memberId)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/management-api/scopes/list).\n\n### Update Scope\n\nUpdates the scope for the specified member in the specified project.\n\n```python\nresponse = deepgram.manage.v(\"1\").update_member_scope(myProjectId, memberId, options)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/management-api/scopes/update).\n\n## Invitations\n\n### List Invites\n\nRetrieves all invitations associated with the provided project_id.\n\n```python\nresponse = deepgram.manage.v(\"1\").get_invites(myProjectId)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/management-api/invitations/list).\n\n### Send Invite\n\nSends an invitation to the provided email address.\n\n```python\nresponse = deepgram.manage.v(\"1\").send_invite(myProjectId, options)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/management-api/invitations/create).\n\n### Delete Invite\n\nRemoves the specified invitation from the project.\n\n```python\nresponse = deepgram.manage.v(\"1\").delete_invite(myProjectId, email)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/management-api/invitations/delete).\n\n### Leave Project\n\n```python\nresponse = deepgram.manage.v(\"1\").leave_project(myProjectId)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/management-api/invitations/leave).\n\n## Usage\n\n### Get All Requests\n\nRetrieves all requests associated with the provided project_id based on the provided options.\n\n```python\nresponse = deepgram.manage.v(\"1\").get_usage_requests(myProjectId)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/management-api/usage/list-requests).\n\n### Get Request\n\nRetrieves a specific request associated with the provided project_id\n\n```python\nresponse = deepgram.manage.v(\"1\").get_usage_request(myProjectId, RequestId)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/management-api/usage/get-request).\n\n### Get Fields\n\nLists the features, models, tags, languages, and processing method used for requests in the specified project.\n\n```python\nresponse = deepgram.manage.v(\"1\").get_usage_fields(myProjectId)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/management-api/usage/list-fields).\n\n### Summarize Usage\n\n`Deprecated` Retrieves the usage for a specific project. Use Get Project Usage Breakdown for a more comprehensive usage summary.\n\n```python\nresponse = deepgram.manage.v(\"1\").get_usage_summary(myProjectId)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/management-api/usage/get).\n\n## Billing\n\n### Get All Balances\n\nRetrieves the list of balance info for the specified project.\n\n```python\nresponse = deepgram.manage.v(\"1\").get_balances(myProjectId)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/management-api/balances/list).\n\n### Get Balance\n\nRetrieves the balance info for the specified project and balance_id.\n\n```python\nresponse = deepgram.manage.v(\"1\").get_balance(myProjectId)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/management-api/balances/get).\n\n## Models\n\n### Get All Project Models\n\nRetrieves all models available for a given project.\n\n```python\nresponse = deepgram.manage.v(\"1\").get_project_models(myProjectId)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/management-api/projects/list-models).\n\n### Get Model\n\nRetrieves details of a specific model.\n\n```python\nresponse = deepgram.manage.v(\"1\").get_project_model(myProjectId, ModelId)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/management-api/projects/get-model).\n\n## On-Prem APIs\n\n### List On-Prem credentials\n\nLists sets of distribution credentials for the specified project.\n\n```python\nresponse = deepgram.selfhosted.v(\"1\").list_selfhosted_credentials(projectId)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/self-hosted-api/list-credentials).\n\n### Get On-Prem credentials\n\nReturns a set of distribution credentials for the specified project.\n\n```python\nresponse = deepgram.selfhosted.v(\"1\").get_selfhosted_credentials(projectId, distributionCredentialsId)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/self-hosted-api/get-credentials).\n\n### Create On-Prem credentials\n\nCreates a set of distribution credentials for the specified project.\n\n```python\nresponse = deepgram.selfhosted.v(\"1\").create_selfhosted_credentials(project_id, options)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/self-hosted-api/create-credentials).\n\n### Delete On-Prem credentials\n\nDeletes a set of distribution credentials for the specified project.\n\n```python\nresponse = deepgram.selfhosted.v(\"1\").delete_selfhosted_credentials(projectId, distributionCredentialId)\n```\n\n[See our API reference for more info](https://developers.deepgram.com/reference/self-hosted-api/delete-credentials).\n\n## Pinning Versions\n\nTo 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](https://discuss.python.org/t/how-to-pin-a-package-to-a-specific-major-version-or-lower/17077) and [dependency management](https://www.easypost.com/dependency-pinning-guide) if you'd like to learn more. For a deeper understanding of how version numbers work, check out[semantic versioning](https://semver.org/).\n\nIn a `requirements.txt` file, you can pin to a specific version like this:\n\n```sh\ndeepgram-sdk==4.1.0\n```\n\nOr using pip:\n\n```sh\npip install deepgram-sdk==4.1.0\n```\n\n## Logging\n\nThis 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:\n\n```python\ndeepgram: DeepgramClient = DeepgramClient()\n```\n\nTo increase the logging output/verbosity for debug or troubleshooting purposes, you can set the `DEBUG` level but using this code:\n\n```python\nconfig: DeepgramClientOptions = DeepgramClientOptions(\n verbose=logging.DEBUG,\n)\ndeepgram: DeepgramClient = DeepgramClient(\"\", config)\n```\n\n## Testing\n\n### Daily and Unit Tests\n\nIf you are looking to use, run, contribute or modify to the daily/unit tests, then you need to install the following dependencies:\n\n```bash\npip install -r requirements-dev.txt\n```\n\n### Daily Tests\n\nThe 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.\n\nTo run the Daily Tests:\n\n```bash\nmake daily-test\n```\n\n#### Unit Tests\n\nThe 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.\n\n```bash\nmake unit-test\n```\n\n## Backwards Compatibility\n\nWe 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.\n\nOlder 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.\n\n## Development and Contributing\n\nInterested in contributing? We \u2764\ufe0f pull requests!\n\nTo make sure our community is safe for all, be sure to review and agree to our\n[Code of Conduct](CODE_OF_CONDUCT.md). Then see the\n[Contribution](CONTRIBUTING.md) guidelines for more information.\n\nIn 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.\n\nFrom the root of the repo, that would entail:\n\n```bash\npip uninstall deepgram-sdk\npip install -r requirements.txt\npip install -e .\n```\n\n## Getting Help\n\nWe love to hear from you so if you have questions, comments or find a bug in the\nproject, let us know! You can either:\n\n- [Open an issue in this repository](https://github.com/deepgram/deepgram-python-sdk/issues/new)\n- [Join the Deepgram Github Discussions Community](https://github.com/orgs/deepgram/discussions)\n- [Join the Deepgram Discord Community](https://discord.gg/xWRaCDBtW4)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "The official Python SDK for the Deepgram automated speech recognition platform.",
"version": "4.7.0",
"project_urls": {
"Homepage": "https://github.com/deepgram/deepgram-python-sdk"
},
"split_keywords": [
"deepgram",
" deepgram speech-to-text"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "336343a6e46b35eae9739e22b5cace4a22ece76d4aff74b563563b9507411484",
"md5": "e14cf072ffbca0c7ea39556678729b9b",
"sha256": "1a2a0890aa43cbc510e07b0f911f6841770ca0222e6fcc069bd3e2afcde1c061"
},
"downloads": -1,
"filename": "deepgram_sdk-4.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e14cf072ffbca0c7ea39556678729b9b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 157911,
"upload_time": "2025-07-21T15:43:55",
"upload_time_iso_8601": "2025-07-21T15:43:55.695587Z",
"url": "https://files.pythonhosted.org/packages/33/63/43a6e46b35eae9739e22b5cace4a22ece76d4aff74b563563b9507411484/deepgram_sdk-4.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "17c73c5918c2c74e3d56cf3d738aa174bc688c73069dc9682fc1bfaeb2058cc6",
"md5": "543a4256f7f5034132191cccc3c939a9",
"sha256": "e371396d8835d449782df472c3bd501f6cad41b3c925f66771933ff3fc4b1a13"
},
"downloads": -1,
"filename": "deepgram_sdk-4.7.0.tar.gz",
"has_sig": false,
"md5_digest": "543a4256f7f5034132191cccc3c939a9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 100128,
"upload_time": "2025-07-21T15:43:56",
"upload_time_iso_8601": "2025-07-21T15:43:56.705062Z",
"url": "https://files.pythonhosted.org/packages/17/c7/3c5918c2c74e3d56cf3d738aa174bc688c73069dc9682fc1bfaeb2058cc6/deepgram_sdk-4.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-21 15:43:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "deepgram",
"github_project": "deepgram-python-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "websockets",
"specs": [
[
">=",
"12.0"
]
]
},
{
"name": "httpx",
"specs": [
[
"==",
"0.*"
]
]
},
{
"name": "dataclasses-json",
"specs": [
[
"==",
"0.*"
]
]
},
{
"name": "dataclasses",
"specs": [
[
"==",
"0.*"
]
]
},
{
"name": "typing_extensions",
"specs": [
[
"==",
"4.*"
]
]
},
{
"name": "aenum",
"specs": [
[
"==",
"3.*"
]
]
},
{
"name": "deprecation",
"specs": [
[
"==",
"2.*"
]
]
},
{
"name": "aiohttp",
"specs": [
[
"==",
"3.*"
]
]
},
{
"name": "aiofiles",
"specs": [
[
"==",
"23.*"
]
]
}
],
"lcname": "deepgram-sdk"
}
JSON
