Skip to main content

​
Overview

Deepgram provides three TTS service implementations:
  • DeepgramTTSService for real-time streaming synthesis using Deepgram’s WebSocket API with support for interruptions and ultra-low latency
  • DeepgramHttpTTSService for batch synthesis using Deepgram’s 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

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: 
pip install "pipecat-ai[deepgram]"
For the SageMaker variant, install the SageMaker dependencies instead: 
pip install "pipecat-ai[sagemaker]"

​
Prerequisites

​
Deepgram Account Setup

Before using DeepgramTTSService or DeepgramHttpTTSService, you need:
  1. Deepgram Account: Sign up at Deepgram Console
  2. API Key: Generate an API key from your project dashboard
  3. 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:
  1. AWS Account: With credentials configured (via environment variables, AWS CLI, or instance metadata)
  2. SageMaker Endpoint: A deployed SageMaker endpoint with a Deepgram TTS model
  3. Voice Selection: Choose from available Aura voice models

​
Configuration

​
DeepgramTTSService

​
api_key
str
required
Deepgram API key for authentication.
​
voice
str
default:"aura-2-helena-en"
deprecated
Voice model to use for synthesis. Deprecated in v0.0.105. Use settings=DeepgramTTSService.Settings(voice=...) instead.
​
settings
DeepgramTTSService.Settings
default:"None"
Runtime-configurable settings. See DeepgramTTSService Settings below.
​
base_url
str
default:"wss://api.deepgram.com"
WebSocket base URL for Deepgram API.
​
sample_rate
int
default:"None"
Output audio sample rate in Hz. When None, uses the pipeline’s configured sample rate.
​
encoding
str
default:"linear16"
Audio encoding format. Must be one of: "linear16", "mulaw", "alaw".

​
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.
ParameterTypeDefaultDescription
modelstrNoneModel identifier. (Inherited.)
voicestrNoneVoice identifier. (Inherited.)
languageLanguage | strNoneLanguage for synthesis. (Inherited.)

​
DeepgramHttpTTSService

​
api_key
str
required
Deepgram API key for authentication.
​
voice
str
default:"aura-2-helena-en"
deprecated
Voice model to use for synthesis. Deprecated in v0.0.105. Use settings=DeepgramHttpTTSService.Settings(voice=...) instead.
​
settings
DeepgramHttpTTSService.Settings
default:"None"
Runtime-configurable settings. See DeepgramHttpTTSService Settings below.
​
aiohttp_session
aiohttp.ClientSession
required
An aiohttp session for HTTP requests. You must create and manage this yourself.
​
base_url
str
default:"https://api.deepgram.com"
HTTP API base URL.
​
sample_rate
int
default:"None"
Output audio sample rate in Hz.
​
encoding
str
default:"linear16"
Audio encoding format.

​
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.
ParameterTypeDefaultDescription
modelstrNoneModel identifier. (Inherited.)
voicestrNoneVoice identifier. (Inherited.)
languageLanguage | strNoneLanguage for synthesis. (Inherited.)

​
DeepgramSageMakerTTSService

​
endpoint_name
str
required
Name of the SageMaker endpoint with Deepgram TTS model deployed.
​
region
str
required
AWS region where the SageMaker endpoint is deployed (e.g., "us-east-2").
​
voice
str
default:"aura-2-helena-en"
deprecated
Voice model to use for synthesis. Deprecated in v0.0.105. Use settings=DeepgramSageMakerTTSService.Settings(voice=...) instead.
​
settings
DeepgramSageMakerTTSService.Settings
default:"None"
Runtime-configurable settings. See DeepgramSageMakerTTSService Settings below.
​
sample_rate
int
default:"None"
Output audio sample rate in Hz. When None, uses the pipeline’s configured sample rate.
​
encoding
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.
ParameterTypeDefaultDescription
modelstrNoneModel identifier. (Inherited.)
voicestrNoneVoice identifier. (Inherited.)
languageLanguage | strNoneLanguage 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",
    ),
)

​
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

  • WebSocket vs HTTP vs SageMaker: The 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.
  • 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.

​
Event Handlers

The WebSocket and SageMaker services support the standard service connection events:
EventDescription
on_connectedConnected to Deepgram (WebSocket or SageMaker)
on_disconnectedDisconnected from Deepgram
on_connection_errorConnection error occurred
@tts.event_handler("on_connected")
async def on_connected(service):
    print("Connected to Deepgram")