Skip to content
Skills Library
AI & agents · Tool integration

deepgram-python-text-to-speech

/deepgram-python-text-to-speech

Use when writing or reviewing Python code in this repo that calls Deepgram Text-to-Speech v1 (`/v1/speak`) for audio synthesis. Covers one-shot REST (`client.speak.v1.audio.generate`) and streaming WebSocket (`client.speak.v1.connect`). Also covers the in-repo `deepgram.helpers.TextBuilder` for incremental text assembly before synthesis. Use `deepgram-python-voice-agent` when you need full-duplex STT + LLM + TTS with barge-in. Triggers include "TTS", "speak", "synthesize voice", "aura", "text to speech", "speak.v1", "TextBuilder".

Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
5
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when writing or reviewing Python code in this repo that calls Deepgram Text-to-Speech v1 (`/v1/speak`) for audio synthesis. Covers one-shot REST (`client.speak.v1.audio.generate`) and streaming WebSocket (`client.speak.v1.connect`). Also covers the in-repo `deepgram.helpers.TextBuilder` for incremental text assembly before synthesis. Use `deepgram-python-voice-agent` when you need full-duplex STT + LLM + TTS with barge-in. Triggers include "TTS", "speak", "synthesize voice", "aura", "text to speech", "speak.v1", "TextBuilder".

Triggers from the description

TTSspeaksynthesize voiceauratext to speechspeak.v1TextBuilder
Original author description

Use when writing or reviewing Python code in this repo that calls Deepgram Text-to-Speech v1 (`/v1/speak`) for audio synthesis. Covers one-shot REST (`client.speak.v1.audio.generate`) and streaming WebSocket (`client.speak.v1.connect`). Also covers the in-repo `deepgram.helpers.TextBuilder` for incremental text assembly before synthesis. Use `deepgram-python-voice-agent` when you need full-duplex STT + LLM + TTS with barge-in. Triggers include "TTS", "speak", "synthesize voice", "aura", "text to speech", "speak.v1", "TextBuilder".

How it works

  1. When to use this product
  2. Authentication
  3. Quick start — REST (one-shot)
  4. Quick start — WebSocket (streaming)
  5. TextBuilder helper (Flux batch controls)
  6. Async equivalents
  7. Key parameters
  8. API reference (layered)
  9. Gotchas
  10. Example files in this repo
Original SKILL.md headings · 160 lines, 718 words
SKILL.md preview
---
name: deepgram-python-text-to-speech
description: Use when writing or reviewing Python code in this repo that calls Deepgram Text-to-Speech v1 (`/v1/speak`) for audio synthesis. Covers one-shot REST (`client.speak.v1.audio.generate`) and streaming WebSocket (`client.speak.v1.connect`). Also covers the in-repo `deepgram.helpers.TextBuilder` for incremental text assembly before synthesis. Use `deepgram-python-voice-agent` when you need full-duplex STT + LLM + TTS with barge-in. Triggers include "TTS", "speak", "synthesize voice", "aura", "text to speech", "speak.v1", "TextBuilder".
---

# Using Deepgram Text-to-Speech (Python SDK)

Convert text to audio: one-shot REST download or low-latency streaming synthesis via `/v1/speak`.

## When to use this product

- **REST (`speak.v1.audio.generate`)** — one-shot synthesis, returns audio bytes. Use for rendered files, pre-generated prompts, anything where you have the full text upfront.
- **WebSocket (`speak.v1.connect`)** — incremental text input, streaming audio output. Use for low-latency playback while an LLM is still producing tokens.

**Use a different skill when:**
- You need the agent to also listen and converse (full-duplex) → `deepgram-python-voice-agent`.

## Authentication

```python
from dotenv import load_dotenv
load_dotenv()

from deepgram import DeepgramClient
client = DeepgramClient()  # reads DEEPGRAM_API_KEY
```

Header: `Authorization: Token <api_key>` (NOT `Bearer`).

## Quick start — REST (one-shot)

```python
audio_iter = client.speak.v1.audio.generate(
    text="Hello, this is a text to speech example.",
    model="aura-2-asteria-en",
    encoding="linear16",
    sample_rate=24000,
)

with open("output.raw", "wb") as f:
    for chunk in audio_iter:
        f.write(chunk)
```

Returns an iterator of `bytes` (streaming audio response). The response body is `audio/*`, NOT JSON. Useful response headers: `dg-model-name`, `dg-char-count`, `dg-request-id`.

## Quick start — WebSocket (streaming)

```python
from deepgram.core.events import EventType
from deepgram.speak.v1.types import SpeakV1Text

with client.speak.v1.connect(
    model="aura-2-asteria-en",
    encoding="linear16",
    sample_rate=24000,
) as conn:
    def on_message(m):
        if isinstance(m, bytes):
            # audio chunk — write to file or audio output
            ...
        else:
            print(f"event: {getattr(m, 'type', 'Unknown')}")

    conn.on(EventType.OPEN,    lambda _: print("open"))
    conn.on(EventType.MESSAGE, on_message)
    conn.on(EventType.CLOSE,   lambda _: print("close"))
    conn.on(EventType.ERROR,   lambda e: print(f"err: {e}"))

    conn.send_text(SpeakV1Text(text="Hello, this is streaming TTS."))
    conn.send_flush()
    conn.send_close()
    conn.start_listening()   # blocks until server closes
```

In **sync** mode, `start_listening()` blocks — send all text + flush + close BEFORE calling it, OR run it in a thread. In **async** mode, run `start_listening()` as a task and send concurrently.

## TextBuilder helper (Flux batch controls)

`deepgram.helpers.TextBuilder` is a hand-maintained helper (NOT Fern-generated) for English Flux batch requests. Pronunciation controls apply to Flux batch, Flux WebSocket, and Aura-2 `/v1/speak`; pauses are Flux batch-only and a Flux WebSocket rejects them with `DATA-0002`.

```python
from deepgram.helpers import TextBuilder

final_text = (
    TextBuilder()
    .text("Hello,")
    .text(" this is built incrementally.")
    .pronunciation("Deepgram", "ˈdiːpɡɹæm")
    .build()
)
```

The fluent API is `.text(...)` (append raw text), `.pronunciation(word, ipa)` (insert a `\{\"word\": \"...\", \"pronounce\": \"...\"\}` marker), `.pause(duration_ms)` (insert a `\{pause:<N>ms\}` marker), and `.build()` (return the batch request text). Pauses must be 500-3000 ms in 100 ms increments, with at most eight per request. Pronunciation and pause cannot be combined in one request; Flux rejects the combination with `CONTROL_COMBINATION_INVALID`. There is no `.add(...)` method.

Use the output with `client.speak.v2.audio.generate(model="flux-alexis-en", text=final_text)`. See `docs/FluxTtsControls.md`, `examples/22-text-builder-demo.py`, and `examples/23-text-builder-helper.py`.

## Async equivalents

```python
from deepgram import AsyncDeepgramClient
client = AsyncDeepgramClient()

# REST
audio_iter = await client.speak.v1.audio.generate(text=..., model="aura-2-asteria-en")
async for chunk in audio_iter:
    ...

# WSS
async with client.speak.v1.connect(model="aura-2-asteria-en", ...) as conn:
    listen_task = asyncio.create_task(conn.start_listening())
    await conn.send_text(SpeakV1Text(text="..."))
    await conn.send_flush()
    await conn.send_close()
    await listen_task
```

## Key parameters

REST & WSS: `model` (e.g. `aura-2-asteria-en`), `encoding` (`linear16`, `mulaw`, `alaw`, `opus`, `flac`, `mp3`, `aac`), `sample_rate`, `bit_rate`, `container`, `callback` (REST async), `tag`, `mip_opt_out`.

WSS client messages: `SpeakV1Text`, `Flush`, `Clear`, `Close`.

## API reference (layered)

1. **In-repo reference**: `reference.md` — sections "Speak V1 Audio" (REST) and "Speak V1 Connect" (WSS).
2. **OpenAPI (REST)**: https://developers.deepgram.com/openapi.yaml
3. **AsyncAPI (WSS)**: https://developers.deepgram.com/asyncapi.yaml
4. **Context7**: library ID `/llmstxt/developers_deepgram_llms_txt`.
5. **Product docs**:
   - https://developers.deepgram.com/reference/text-to-speech/speak-request
   - https://developers.deepgram.com/reference/text-to-speech/speak-streaming
   - https://developers.deepgram.com/docs/tts-models

## Gotchas

1. **`Token` auth, not `Bearer`.**
2. **REST response is audio bytes, not JSON.** Iterate the response; don't `.json()` it.
3. **Flush before close (WSS).** `send_close()` without `send_flush()` may drop trailing audio.
4. **Sync `start_listening()` blocks.** Queue all messages first, or use async.
5. **`SpeakV1Text` is required** for WSS text input — don't send raw strings.
6. **`encoding`/`sample_rate`/`container` must match your playback path.** Mismatches cause silent failure or distortion.
7. **`TextBuilder` helpers are hand-maintained** (listed in `.fernignore` as permanently frozen). Don't move them under `src/deepgram/` auto-generated paths.

## Example files in this repo

- `examples/20-text-to-speech-single.py` — REST one-shot
- `examples/21-text-to-speech-streaming.py` — WSS streaming
- `examples/22-text-builder-demo.py` — TextBuilder (no API key)
- `examples/23-text-builder-helper.py` — TextBuilder + REST
- `examples/24-text-builder-streaming.py` — plain-text WSS; Flux pause controls are batch-only
- `tests/wire/test_speak_v1_audio.py` — REST wire test
- `tests/manual/speak/v1/connect/main.py` — live WSS test

## Central product skills

For cross-language Deepgram product knowledge — the consolidated API reference, documentation finder, focused runnable recipes, third-party integration examples, and MCP setup — install the central skills:

```bash
npx skills add deepgram/skills
```

This SDK ships language-idiomatic code skills; `deepgram/skills` ships cross-language product knowledge (see `api`, `docs`, `recipes`, `examples`, `starters`, `setup-mcp`).

Versions

The database has no other skills named deepgram-python-text-to-speech.

Database snapshot: 13.11.2026 · package version b3cbf0b160e3 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100deepgram-js-text-to-speech
    Use when writing or reviewing JavaScript/TypeScript in this repo that calls Deepgram Text-to-Speech v1 (`/v1/speak`) for audio synthesis. Covers one-shot REST via `client.speak.v1.audio.generate` and streaming WebSocket via `client.speak.v1.createConnection()` / `connect()`. Use…
  • 100deepgram-java-text-to-speech
    Use when writing or reviewing Java code in this repo that calls Deepgram Text-to-Speech v1 (`/v1/speak`) for audio synthesis. Covers one-shot REST via `client.speak().v1().audio().generate(...)` and streaming synthesis via `client.speak().v1().v1WebSocket()`. Use…
  • 100deepgram-python-voice-agent
    Use when writing or reviewing Python code in this repo that builds an interactive voice agent via `agent.deepgram.com/v1/agent/converse`. Covers `client.agent.v1.connect()`, `AgentV1Settings`, `send_settings`, `send_media`, event handling, and function/tool calling. Full-duplex…
  • 100deepgram-python-speech-to-text
    Use when writing or reviewing Python code in this repo that calls Deepgram Speech-to-Text v1 (`/v1/listen`) for prerecorded or live audio transcription. Covers `client.listen.v1.media.transcribe_url` / `transcribe_file` (REST) and `client.listen.v1.connect` (WebSocket). Use this…
  • 100deepgram-go-text-to-speech
    Use when writing or reviewing Go code in this repo that synthesizes audio with Speak v1 REST or Speak WebSockets. Route transcription work to deepgram-go-speech-to-text, voice conversation runtime work to deepgram-go-voice-agent, and repository maintenance work to deepgram-go-maintaining-sdk.
  • 100deepgram-js-speech-to-text
    Use when writing or reviewing JavaScript/TypeScript in this repo that calls Deepgram Speech-to-Text v1 (`/v1/listen`) for prerecorded or live audio transcription. Covers `client.listen.v1.media.transcribeUrl` / `transcribeFile` (REST) plus `client.listen.v1.createConnection()` /…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.