deepgram-sdk: one client for Deepgram speech, text and voice agents

What the SDK wraps

The Deepgram Python SDK is the official client for Deepgram's automated speech recognition, text to speech and language understanding APIs. The README groups the surface into five areas.

Listen covers speech to text, with file transcription, URL transcription and media processing, plus real-time streaming through Listen v1 and v2 WebSocket connections. Speak is text to speech. Read is text intelligence: sentiment, summarization, topic and intent detection on text you already have. Manage covers projects, API keys and usage analytics. Auth handles token generation.

There is also an Agent surface for building voice agents, which is the newest and most composed part of the library.

The important framing is that this is a client. No model runs locally, nothing is downloaded except the package, and every call goes to Deepgram over the network. That determines most of what follows: latency is network plus service, cost is per unit of audio, and availability is Deepgram's.

Python 3.10 or newer is required, and the package is MIT licensed.

Installing and authenticating

Installation is a single package, and note the name is deepgram-sdk rather than deepgram:

pip install deepgram-sdk

The SDK discovers credentials from the environment automatically, so the simplest client construction reads DEEPGRAM_API_KEY and needs no argument:

from deepgram import DeepgramClient

client = DeepgramClient()

The README documents two credential types. An API key is for server-side use, passed explicitly as DeepgramClient(api_key="YOUR_API_KEY") or picked up from DEEPGRAM_API_KEY. An access token is for temporary or scoped access, which the README recommends for client-side applications, passed as access_token or read from DEEPGRAM_TOKEN, and generated from an API key through auth.v1.tokens.grant().

One behaviour from the release notes is worth knowing in multi-tenant code: passing api_key=None explicitly continues to disable the ambient DEEPGRAM_API_KEY lookup. That was called out as a fix in v7.8.1 because it matters for test environments where a developer's own key would otherwise leak into a client that was supposed to have none.

Transcribing a file

The file transcription path takes the bytes of an audio file:

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",
        language="en",
    )
    print(response.results.channels[0].alternatives[0].transcript)

The README adds a language note that is easy to get wrong: nova-3 uses English when language is omitted, so non-English audio needs an explicit language such as "fr". For unknown audio, detect_language=True handles a single dominant language, and language="multi" handles audio that may contain several supported languages.

For real-time audio, the README's Listen v2 example connects over a WebSocket with flux-general-en, described as the newest model with contextual turn detection. The pattern is an event-driven connection where you register handlers for EventType.OPEN, MESSAGE, CLOSE and ERROR, then call start_listening and send audio, with encoding and sample_rate specified at connect time.

That split is the usual one: v1 media for files, v2 streaming for live audio.

Speech synthesis and text intelligence

Text to speech streams back in chunks, which the README's example writes to a file:

response = client.speak.v1.audio.generate(
    text="Hello, this is a sample text to speech conversion."
)

with open("output.mp3", "wb") as audio_file:
    for chunk in response:
        audio_file.write(chunk)

Recent releases have been changing the synthesis parameters. Version 7.9.0 widened Flux TTS speed to accept 0.5 through 1.5 in 0.05 increments, replacing a previously documented 0.85 through 1.15 range, and added an integer expressivity setting from -2 through 2 for Deepgram Flux TTS providers. The same release removed aura-2-perseo-it from the model literals because the API never served it and returns 400 for it.

Text intelligence is a separate service that takes text rather than audio, with flags for sentiment, summarize, topics and intents. It is the part of the SDK most likely to be overlooked, and it is useful when you already have transcripts and want structure from them without another vendor.

The voice agent is three providers

The Agent surface is the clearest statement of what Deepgram thinks a voice agent is. The README's example builds an AgentV1Settings object with three independently chosen providers: a listen provider for speech to text, a think provider for the language model, and a speak provider for synthesis.

In the example, listen is Deepgram's own nova-3, think is OpenAI's gpt-4o-mini with a prompt, and speak is Deepgram's aura-2-asteria-en. Audio input is configured separately with encoding and sample rate, and the session is driven by send_settings and start_listening.

That composition is the useful part. You can keep Deepgram for the audio and put a different model in the middle, which is what most teams want to do anyway, and the SDK treats the three as configuration rather than as a fixed pipeline.

Version 7.9.0 added send_force_end_turn() and typed ForceEndTurn messages for V2 Flux listen providers, which is the kind of control you need when turn detection gets it wrong and the agent keeps waiting.

The cost of this design is surface area. The agent example imports settings types from four different modules, which is a lot of ceremony for one call.

Migration history is the maintenance signal

The documentation directory carries four migration guides: v2 to v3, v3 to v5, v5 to v6 and v6 to v7. Four breaking transitions in a client library is a lot, and it tells you what adopting this costs over time.

The README links the v6 to v7 guide as current. If you are picking this up fresh you start at v7 and never see the earlier ones, but if you inherit a codebase using it, expect the upgrade to be work rather than a version bump.

The repository shows why the churn happens: there is a .fern directory, and the README carries a Built with Fern badge, so the SDK is generated from an API specification rather than hand-written. Generation keeps client and API in step and produces consistent types, and it also means releases can move parameter names and module paths without much notice, because they follow the spec rather than a hand-maintained compatibility layer.

Version 7.9.0 was published on 2026-09-14 and 7.8.1 on 2026-09-03, both on the same day as or close to the last push to the repository, so releases track the service closely.

Running speech locally as the alternative

The alternative is not another SDK, it is not making the call. A local speech to text setup, for example faster-whisper running Whisper through CTranslate2, puts transcription on your own hardware with no per-minute cost and no audio leaving your network.

The difference is who operates it. Locally you choose the model size, you own the GPU, you handle concurrency and you accept that accuracy and speed depend on your hardware and model choice. With Deepgram you send audio and get a transcript, latency is low because the service is built for it, and you pay by usage.

The decision usually turns on volume and data sensitivity. High volume with predictable load favours running your own. Variable load, no GPU capacity, or audio that cannot leave a jurisdiction point in different directions: the last one favours local, the middle one favours the API.

It is also worth noting that the SDK covers more than transcription. Text intelligence and the agent composition layer have no equivalent in a local Whisper setup, so the comparison is only fair on the speech to text part.

Licence and upkeep

The SDK is MIT licensed, so using and modifying the client is unrestricted. The service behind it is commercial, and the README does not discuss pricing, so cost is something to establish with Deepgram rather than from the repository.

The repository is set up for generated-code maintenance: a .fern directory for the generator configuration, wiremock/ for recorded HTTP interactions in tests, a .coveragerc, a reference.md documenting every method, and examples/ alongside docs/. There are AGENTS.md and CLAUDE.md files at the root.

The main upkeep cost is version transitions. With four migration guides behind it, the realistic posture is to pin the version, read the changelog before bumping, and keep the transcription call in one place in your code so a v8 migration touches one file.

The v7.9.0 removal of aura-2-perseo-it is a small illustration of the general risk: a model name can exist in the SDK's type literals and still be rejected by the API with a 400.

Editorial conclusion

Adopt deepgram-sdk if you want hosted speech to text, text to speech, text intelligence and voice agents behind one Python client and you are comfortable with a commercial API in the path. The agent composition layer, where listen, think and speak providers are configured independently, is the strongest reason to choose it over assembling the pieces yourself. Do not adopt it if the audio cannot leave your network or your volume makes per-minute pricing wrong, in which case a local Whisper setup is the comparison to make. Before committing, pin the version and read the migration guides, because the library carries four of them from v2 through v7 and is generated from an API spec, so parameter changes arrive with releases. Set credentials through DEEPGRAM_API_KEY, and pass api_key=None explicitly in tests to stop an ambient key being picked up.

Frequently asked questions

Official sources

1. deepgram/deepgram-python-sdk on GitHub
2. License: MIT
3. Project website
4. README
5. Releases