Deepgram

Overview

Deepgram provides four TTS service implementations:

DeepgramFluxTTSService for real-time synthesis using Deepgram’s Flux WebSocket API, a streaming-first service designed for voice agents with token-level streaming and cross-turn prosody state
DeepgramTTSService for real-time streaming synthesis using Deepgram’s Aura WebSocket API with support for interruptions and ultra-low latency
DeepgramHttpTTSService for batch synthesis using Deepgram’s Aura HTTP API
DeepgramSageMakerTTSService for real-time synthesis using Deepgram TTS models deployed on AWS SageMaker endpoints via HTTP/2 bidirectional streaming

Deepgram TTS API Reference

Pipecat’s API methods for Deepgram TTS integration

Example Implementation

Complete example with Silero VAD

Flux Example

Complete example with Flux STT and TTS

SageMaker Example

Complete example with Deepgram on SageMaker

Deepgram Documentation

Official Deepgram Aura TTS API documentation

Voice Models

Browse available Aura voice models

Installation

To use Deepgram TTS services, install the required dependencies:

uv add "pipecat-ai[deepgram]"

For the SageMaker variant, install the SageMaker dependencies instead:

uv add "pipecat-ai[sagemaker]"

Prerequisites

Deepgram Account Setup

Before using DeepgramTTSService or DeepgramHttpTTSService, you need:

Deepgram Account: Sign up at Deepgram Console
API Key: Generate an API key from your project dashboard
Voice Selection: Choose from available Aura voice models

Required Environment Variables

DEEPGRAM_API_KEY: Your Deepgram API key for authentication

AWS SageMaker Setup

Before using DeepgramSageMakerTTSService, you need:

AWS Account: With credentials configured (via environment variables, AWS CLI, or instance metadata)
SageMaker Endpoint: A deployed SageMaker endpoint with a Deepgram TTS model
Voice Selection: Choose from available Aura voice models

Flux Setup

Before using DeepgramFluxTTSService, you need:

Deepgram Account: Sign up at Deepgram Console
API Key: Generate an API key with Flux TTS access
Voice Selection: Choose from available Flux voice models (flux-{voice}-{language})

Configuration

DeepgramFluxTTSService

str

required

Deepgram API key for authentication.

str

default:"wss://api.deepgram.com/v2/speak"

WebSocket URL for the Flux TTS API.

int

default:"None"

Audio sample rate in Hz. When None, uses the pipeline’s configured sample rate. Must be one of: 8000, 16000, 24000, 32000, 44100, 48000.

bool | None

default:"None"

Opt out of the Deepgram Model Improvement Program (MIP). See the MIP Guide for pricing impacts before setting to True.

list[str] | None

default:"None"

Tags to label requests for identification during usage reporting.

TextAggregationMode

default:"TextAggregationMode.TOKEN"

How to aggregate incoming text before synthesis. Defaults to TOKEN, streaming LLM tokens straight to Flux for the lowest latency. Pass TextAggregationMode.SENTENCE to aggregate text into sentences before synthesis.

DeepgramFluxTTSService.Settings

default:"None"

Runtime-configurable settings. See DeepgramFluxTTSService Settings below.

DeepgramFluxTTSService Settings

Runtime-configurable settings passed via the settings constructor argument using DeepgramFluxTTSService.Settings(...). These can be updated mid-conversation with TTSUpdateSettingsFrame. See Service Settings for details.

Parameter	Type	Default	Description
`voice`	`str`	`flux-alexis-en`	Flux voice identifier (e.g., `flux-alexis-en`, `flux-drew-en`).
`model`	`str`	(synced to voice)	Model identifier. Automatically set to match `voice`. (Inherited.)
`language`	`Language \| str`	`None`	Language for synthesis. (Inherited.)

The model field is automatically kept in sync with voice for metrics tracking. Deepgram’s Flux API uses the voice identifier as its model parameter.

DeepgramTTSService

str

required

Deepgram API key for authentication.

str

default:"aura-2-helena-en"

deprecated

Voice model to use for synthesis. Deprecated in v0.0.105. Use settings=DeepgramTTSService.Settings(voice=...) instead.

DeepgramTTSService.Settings

default:"None"

Runtime-configurable settings. See DeepgramTTSService Settings below.

str

default:"wss://api.deepgram.com"

WebSocket base URL for Deepgram API.

int

default:"None"

Output audio sample rate in Hz. When None, uses the pipeline’s configured sample rate.

str

default:"linear16"

Audio encoding format. Must be one of: "linear16", "mulaw", "alaw".

bool | None

default:"None"

Opt out of the Deepgram Model Improvement Program (MIP). See the MIP Guide for pricing impacts before setting to True.

DeepgramTTSService Settings

Runtime-configurable settings passed via the settings constructor argument using DeepgramTTSService.Settings(...). These can be updated mid-conversation with TTSUpdateSettingsFrame. See Service Settings for details.

Parameter	Type	Default	Description
`model`	`str`	`None`	Model identifier. (Inherited.)
`voice`	`str`	`None`	Voice identifier. (Inherited.)
`language`	`Language \| str`	`None`	Language for synthesis. (Inherited.)

DeepgramHttpTTSService

str

required

Deepgram API key for authentication.

str

default:"aura-2-helena-en"

deprecated

Voice model to use for synthesis. Deprecated in v0.0.105. Use settings=DeepgramHttpTTSService.Settings(voice=...) instead.

DeepgramHttpTTSService.Settings

default:"None"

Runtime-configurable settings. See DeepgramHttpTTSService Settings below.

aiohttp.ClientSession

required

An aiohttp session for HTTP requests. You must create and manage this yourself.

str

default:"https://api.deepgram.com"

HTTP API base URL.

int

default:"None"

Output audio sample rate in Hz.

str

default:"linear16"

Audio encoding format.

bool | None

default:"None"

Opt out of the Deepgram Model Improvement Program (MIP). See the MIP Guide for pricing impacts before setting to True.

DeepgramHttpTTSService Settings

Runtime-configurable settings passed via the settings constructor argument using DeepgramHttpTTSService.Settings(...). These can be updated mid-conversation with TTSUpdateSettingsFrame. See Service Settings for details.

Parameter	Type	Default	Description
`model`	`str`	`None`	Model identifier. (Inherited.)
`voice`	`str`	`None`	Voice identifier. (Inherited.)
`language`	`Language \| str`	`None`	Language for synthesis. (Inherited.)

DeepgramSageMakerTTSService

str

required

Name of the SageMaker endpoint with Deepgram TTS model deployed.

str

required

AWS region where the SageMaker endpoint is deployed (e.g., "us-east-2").

str

default:"aura-2-helena-en"

deprecated

Voice model to use for synthesis. Deprecated in v0.0.105. Use settings=DeepgramSageMakerTTSService.Settings(voice=...) instead.

DeepgramSageMakerTTSService.Settings

default:"None"

Runtime-configurable settings. See DeepgramSageMakerTTSService Settings below.

int

default:"None"

Output audio sample rate in Hz. When None, uses the pipeline’s configured sample rate.

str

default:"linear16"

Audio encoding format.

DeepgramSageMakerTTSService Settings

Runtime-configurable settings passed via the settings constructor argument using DeepgramSageMakerTTSService.Settings(...). These can be updated mid-conversation with TTSUpdateSettingsFrame. See Service Settings for details.

Parameter	Type	Default	Description
`model`	`str`	`None`	Model identifier. (Inherited.)
`voice`	`str`	`None`	Voice identifier. (Inherited.)
`language`	`Language \| str`	`None`	Language for synthesis. (Inherited.)

Usage

Basic Setup

from pipecat.services.deepgram import DeepgramTTSService

tts = DeepgramTTSService(
    api_key=os.getenv("DEEPGRAM_API_KEY"),
    settings=DeepgramTTSService.Settings(
        voice="aura-2-helena-en",
    ),
)

Flux Service

from pipecat.services.deepgram.flux.tts import DeepgramFluxTTSService

tts = DeepgramFluxTTSService(
    api_key=os.getenv("DEEPGRAM_API_KEY"),
    settings=DeepgramFluxTTSService.Settings(
        voice="flux-alexis-en",
    ),
)

To aggregate text into sentences before synthesis instead of streaming tokens, pass text_aggregation_mode:

from pipecat.services.tts_service import TextAggregationMode

tts = DeepgramFluxTTSService(
    api_key=os.getenv("DEEPGRAM_API_KEY"),
    text_aggregation_mode=TextAggregationMode.SENTENCE,
    settings=DeepgramFluxTTSService.Settings(
        voice="flux-alexis-en",
    ),
)

HTTP Service

import aiohttp
from pipecat.services.deepgram import DeepgramHttpTTSService

async with aiohttp.ClientSession() as session:
    tts = DeepgramHttpTTSService(
        api_key=os.getenv("DEEPGRAM_API_KEY"),
        settings=DeepgramHttpTTSService.Settings(
            voice="aura-2-helena-en",
        ),
        aiohttp_session=session,
    )

SageMaker Service

from pipecat.services.deepgram.sagemaker.tts import DeepgramSageMakerTTSService

tts = DeepgramSageMakerTTSService(
    endpoint_name=os.getenv("SAGEMAKER_TTS_ENDPOINT_NAME"),
    region=os.getenv("AWS_REGION"),
    settings=DeepgramSageMakerTTSService.Settings(
        voice="aura-2-helena-en",
    ),
)

The InputParams / params= pattern is deprecated as of v0.0.105. Use Settings / settings= instead. See the Service Settings guide for migration details.

Notes

Choosing a service: The Aura WebSocket service (DeepgramTTSService) and SageMaker service (DeepgramSageMakerTTSService) both support real-time streaming with interruption handling, making them suitable for interactive conversations. The HTTP service (DeepgramHttpTTSService) is simpler but processes each request as a batch. The Flux service (DeepgramFluxTTSService) is a streaming-first option built for voice agents, with token-level streaming and cross-turn prosody state.
Encoding validation: The WebSocket service validates the encoding parameter at initialization and raises a ValueError for unsupported formats.
SageMaker deployment: The SageMaker service requires a Deepgram TTS model deployed to an AWS SageMaker endpoint. See the Deepgram SageMaker deployment guide for setup instructions.

Flux notes

Token Streaming: By default (TextAggregationMode.TOKEN), LLM tokens are sent to Flux immediately without buffering for sentence boundaries. Flux internally determines synthesis boundaries, so aggregating sentences typically only adds latency.
Cross-Turn Prosody: Flux maintains acoustic state across turns on a single connection, preserving prosody and pacing throughout the conversation. This state resets on reconnection (interruption or server session timeout).
Interruption Handling: Flux does not yet provide a message to cancel the active turn. Interruptions are handled by reconnecting the websocket, which resets the cross-turn prosody state. Once Deepgram ships the planned Interrupt message, interruptions will be handled without reconnection.
Sample Rate Validation: Only the rates 8000, 16000, 24000, 32000, 44100, and 48000 Hz are supported. An explicit unsupported rate raises a ValueError at initialization.
Audio Format: Flux audio is always returned as linear PCM (linear16), the format used internally by Pipecat pipelines.

Event Handlers

The WebSocket, SageMaker, and Flux services support the standard service connection events:

Event	Description
`on_connected`	Connected to Deepgram (WebSocket or SageMaker)
`on_disconnected`	Disconnected from Deepgram
`on_connection_error`	Connection error occurred

@tts.event_handler("on_connected")
async def on_connected(service):
    print("Connected to Deepgram")

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Pipecat Context Hub

Overview

Deepgram TTS API Reference

Example Implementation

Flux Example

SageMaker Example

Deepgram Documentation

Voice Models

Installation

Prerequisites

Deepgram Account Setup

Required Environment Variables

AWS SageMaker Setup

Flux Setup

Configuration

DeepgramFluxTTSService

DeepgramFluxTTSService Settings

DeepgramTTSService

DeepgramTTSService Settings

DeepgramHttpTTSService

DeepgramHttpTTSService Settings

DeepgramSageMakerTTSService

DeepgramSageMakerTTSService Settings

Usage

Basic Setup

Flux Service

HTTP Service

SageMaker Service

Notes

Flux notes

Event Handlers

​Overview

Deepgram TTS API Reference

Example Implementation

Flux Example

SageMaker Example

Deepgram Documentation

Voice Models

​Installation

​Prerequisites

​Deepgram Account Setup

​Required Environment Variables

​AWS SageMaker Setup

​Flux Setup

​Configuration

​DeepgramFluxTTSService

​DeepgramFluxTTSService Settings

​DeepgramTTSService

​DeepgramTTSService Settings

​DeepgramHttpTTSService

​DeepgramHttpTTSService Settings

​DeepgramSageMakerTTSService

​DeepgramSageMakerTTSService Settings

​Usage

​Basic Setup

​Flux Service

​HTTP Service

​SageMaker Service

​Notes

​Flux notes

​Event Handlers

Overview

Installation

Prerequisites

Deepgram Account Setup

Required Environment Variables

AWS SageMaker Setup

Flux Setup

Configuration

DeepgramFluxTTSService

DeepgramFluxTTSService Settings

DeepgramTTSService

DeepgramTTSService Settings

DeepgramHttpTTSService

DeepgramHttpTTSService Settings

DeepgramSageMakerTTSService

DeepgramSageMakerTTSService Settings

Usage

Basic Setup

Flux Service

HTTP Service

SageMaker Service

Notes

Flux notes

Event Handlers