deepgram-python-sdk

The Deepgram Python SDK is the official client library for Deepgram’s speech AI platform, wrapping automated speech recognition, text-to-speech, text intelligence, and real-time voice agent APIs behind a single typed interface. Generated from Deepgram’s API specification with Fern, it exposes synchronous and asynchronous clients that share the same surface, along with WebSocket-based streaming connections for the newest Listen v2 real-time transcription model and the Agent v1 conversational voice pipeline.

Beyond raw HTTP calls, the SDK adds pydantic-validated request/response models, automatic retries with exponential backoff for 408/429/5xx errors, a pluggable transport interface so WebSocket connections can be swapped for custom implementations (including a SageMaker-backed transport for self-hosted deployments), and helpers for generating short-lived access tokens from a long-lived API key.

What You Get

• A single DeepgramClient / AsyncDeepgramClient covering listen, speak, read, agent, manage, and auth endpoints
• WebSocket streaming clients for real-time transcription (Listen v1/v2), streaming TTS (Speak v1/v2), and the conversational Agent v1 pipeline
• Pydantic-validated request and response models with full type hints (py.typed) for editor autocomplete and static checking
• A pluggable transport interface so WebSocket connections can be swapped for custom implementations, including a ready-made AWS SageMaker transport for self-hosted models
• Built-in retry logic with exponential backoff, raw-response access, and configurable per-request timeouts

Common Use Cases

• Transcribing pre-recorded audio files or remote URLs into text with speaker diarization, punctuation, and summarization
• Streaming live microphone or telephony audio to Deepgram for low-latency real-time transcription
• Converting text responses into natural-sounding speech for voice assistants and IVR systems
• Building conversational voice agents that combine Deepgram’s ASR, an LLM, and TTS in one WebSocket session
• Generating and rotating short-lived access tokens for client-side or edge applications

Under The Hood

Architecture The SDK is generated by Fern from Deepgram’s API specification and layers three tiers: base_client.py defines BaseClient/AsyncBaseClient, lazily exposing typed sub-clients (listen, speak, read, agent, manage, auth, self_hosted, voice_agent) as properties; client.py extends those generated classes with hand-written cross-cutting behavior — access-token vs. API-key authorization, an auto-generated x-deepgram-session-id header, and a transport_factory hook that swaps the default websockets transport for a caller-supplied implementation satisfying a documented send/recv/__iter__/close protocol (transport_interface.py); and each API area (e.g. listen/v1, listen/v2) has its own client.py plus raw_client.py for .with_raw_response access to headers. Shared plumbing — retries, error parsing, pydantic (de)serialization, SSE handling — lives under core/, so swapping transports or adding an endpoint doesn’t touch business logic elsewhere; the main risk if base_client.py’s lazy-property pattern changed would be breaking every generated sub-client’s import path at once.

Tech Stack Pure Python 3.10+ built on httpx for HTTP (sync and async), websockets for streaming connections (with an optional httpx-aiohttp/aiohttp backend), and pydantic (both v1 and v2 compatible via pydantic-core) for request/response models. Packaging is Poetry-driven (pyproject.toml/poetry.lock), with mypy for static typing, ruff for linting, and pytest/pytest-asyncio/pytest-xdist/respx for testing — all declared as dev dependencies rather than bundled with the runtime install.

Code Quality The repo carries an extensive test suite (over 100 test files) split into tests/wire (mocked wire-level request/response contract tests per endpoint, auto-generated alongside the client code), tests/custom and tests/manual (hand-written behavioral tests), and tests/typecheck (mypy-checked usage snippets). CI runs a matrix across Python 3.10-3.13, compiles with mypy src/, type-checks the test suite separately, and runs the full pytest suite with coverage (.coveragerc) — errors are raised as typed ApiError/subclasses rather than swallowed, and the package ships py.typed for downstream type-checking.

API Design The client mirrors Deepgram’s product surface directly in its namespace (client.listen.v1.media, client.speak.v1.audio, client.agent.v1.connect), keeping method names close to REST/WebSocket operation names so the SDK reads as a thin, discoverable layer over the API rather than an abstraction with its own vocabulary. Getting started requires only a client instantiation plus one call (client.listen.v1.media.transcribe_file(...)), credentials are picked up automatically from DEEPGRAM_API_KEY/DEEPGRAM_TOKEN env vars, and advanced needs (custom transports, raw responses, per-request timeouts/retries) are opt-in via extra kwargs rather than required boilerplate, though the auto-generated nature of the client produces some verbose nested-settings types for streaming APIs like the voice agent.