Skip to main content

The official Python SDK for the Deepgram automated speech recognition platform.

Project description

Deepgram Python SDK

Contributor Covenant

This SDK is under active development; feel free to provide feedback via GitHub issues and suggest new features.

Official Python SDK for Deepgram's automated speech recognition APIs.

To access the API you will need a Deepgram account. Sign up for free at

You can learn more about the full Deepgram API at

Getting Started

pip install deepgram-sdk
from deepgram import Deepgram

dg_client = Deepgram(YOUR_API_KEY)
# or, fully specify for an alternate endpoint
dg_client = Deepgram({
    'api_key': YOUR_API_KEY,
    'api_url': YOUR_API_URL


Basic transcription can be done like so:

Batch processing

from deepgram import Deepgram
import asyncio, json

PATH_TO_FILE = 'some/file.wav'

async def main():
    # Initializes the Deepgram SDK
    dg_client = Deepgram(DEEPGRAM_API_KEY)
    # Open the audio file
    with open(PATH_TO_FILE, 'rb') as audio:
        # ...or replace mimetype as appropriate
        source = {'buffer': audio, 'mimetype': 'audio/wav'}
        response = await dg_client.transcription.prerecorded(source, {'punctuate': True})
        print(json.dumps(response, indent=4))

"Fake" streaming processing:

from deepgram import Deepgram
import asyncio, json

PATH_TO_FILE = 'some/file.wav'

async def main():
    # Initializes the Deepgram SDK
    dg_client = Deepgram(DEEPGRAM_API_KEY)
    # Creates a websocket connection to Deepgram
        socket = await{'punctuate': True})
    except Exception as e:
        print(f'Could not open socket: {e}')
    # Handle sending audio to the socket
    async def process_audio(connection):
        # Open the file
        with open(PATH_TO_FILE, 'rb') as audio:
            # Chunk up the audio to send
            CHUNK_SIZE_BYTES = 8192
            CHUNK_RATE_SEC = 0.001
            chunk =
            while chunk:
                await asyncio.sleep(CHUNK_RATE_SEC)
                chunk =
        # Indicate that we've finished sending data
        await connection.finish()

    # Listen for the connection to close
    socket.register_handler(socket.event.CLOSE, lambda c: print(f'Connection closed with code {c}.'))
    # Print incoming transcription objects
    socket.register_handler(socket.event.TRANSCRIPT_RECEIVED, print)

    # Send the audio to the socket
    await process_audio(socket)


Query parameters like punctuate are added as part of the TranscriptionOptions dict in the .prerecorded/.live transcription call. Multiple query parameters can be added similarly, and any dict will do - the types are provided for reference/convenience.

response = await dg_client.transcription.prerecorded(source, {'punctuate': True, 'keywords': ['first:5', 'second']})

Depending on your preference, you can also add parameters as named arguments, instead.

response = await dg_client.transcription.prerecorded(source, punctuate=True, keywords=['first:5', 'second'])

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. Then see the Contribution guidelines for more information.

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:

Further Reading

Check out the Developer Documentation at

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

deepgram-sdk-0.2.4.tar.gz (12.2 kB view hashes)

Uploaded source

Built Distribution

deepgram_sdk-0.2.4-py3-none-any.whl (12.9 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page