> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Deepgram

> Text-to-speech service implementations using Deepgram's Aura API

## 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

<CardGroup cols={2}>
  <Card title="Deepgram TTS API Reference" icon="code" href="https://reference-server.pipecat.ai/en/latest/api/pipecat.services.deepgram.tts.html">
    Pipecat's API methods for Deepgram TTS integration
  </Card>

  <Card title="Example Implementation" icon="play" href="https://github.com/pipecat-ai/pipecat/blob/main/examples/voice/voice-deepgram.py">
    Complete example with Silero VAD
  </Card>

  <Card title="SageMaker Example" icon="play" href="https://github.com/pipecat-ai/pipecat/blob/main/examples/voice/voice-deepgram-sagemaker.py">
    Complete example with Deepgram on SageMaker
  </Card>

  <Card title="Deepgram Documentation" icon="book" href="https://developers.deepgram.com/reference/text-to-speech-api/speak">
    Official Deepgram Aura TTS API documentation
  </Card>

  <Card title="Voice Models" icon="microphone" href="https://developers.deepgram.com/docs/tts-models">
    Browse available Aura voice models
  </Card>
</CardGroup>

## Installation

To use Deepgram TTS services, install the required dependencies:

```bash theme={null}
uv add "pipecat-ai[deepgram]"
```

For the SageMaker variant, install the SageMaker dependencies instead:

```bash theme={null}
uv add "pipecat-ai[sagemaker]"
```

## Prerequisites

### Deepgram Account Setup

Before using `DeepgramTTSService` or `DeepgramHttpTTSService`, you need:

1. **Deepgram Account**: Sign up at [Deepgram Console](https://console.deepgram.com/)
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](https://developers.deepgram.com/docs/deploy-amazon-sagemaker)
3. **Voice Selection**: Choose from available Aura voice models

## Configuration

### DeepgramTTSService

<ParamField path="api_key" type="str" required>
  Deepgram API key for authentication.
</ParamField>

<ParamField path="voice" type="str" default="aura-2-helena-en" deprecated>
  Voice model to use for synthesis. *Deprecated in v0.0.105. Use
  `settings=DeepgramTTSService.Settings(voice=...)` instead.*
</ParamField>

<ParamField path="settings" type="DeepgramTTSService.Settings" default="None">
  Runtime-configurable settings. See [DeepgramTTSService
  Settings](#deepgramttsservice-settings) below.
</ParamField>

<ParamField path="base_url" type="str" default="wss://api.deepgram.com">
  WebSocket base URL for Deepgram API.
</ParamField>

<ParamField path="sample_rate" type="int" default="None">
  Output audio sample rate in Hz. When `None`, uses the pipeline's configured
  sample rate.
</ParamField>

<ParamField path="encoding" type="str" default="linear16">
  Audio encoding format. Must be one of: `"linear16"`, `"mulaw"`, `"alaw"`.
</ParamField>

#### 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](/pipecat/fundamentals/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

<ParamField path="api_key" type="str" required>
  Deepgram API key for authentication.
</ParamField>

<ParamField path="voice" type="str" default="aura-2-helena-en" deprecated>
  Voice model to use for synthesis. *Deprecated in v0.0.105. Use
  `settings=DeepgramHttpTTSService.Settings(voice=...)` instead.*
</ParamField>

<ParamField path="settings" type="DeepgramHttpTTSService.Settings" default="None">
  Runtime-configurable settings. See [DeepgramHttpTTSService
  Settings](#deepgramhttpttsservice-settings) below.
</ParamField>

<ParamField path="aiohttp_session" type="aiohttp.ClientSession" required>
  An aiohttp session for HTTP requests. You must create and manage this
  yourself.
</ParamField>

<ParamField path="base_url" type="str" default="https://api.deepgram.com">
  HTTP API base URL.
</ParamField>

<ParamField path="sample_rate" type="int" default="None">
  Output audio sample rate in Hz.
</ParamField>

<ParamField path="encoding" type="str" default="linear16">
  Audio encoding format.
</ParamField>

#### 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](/pipecat/fundamentals/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

<ParamField path="endpoint_name" type="str" required>
  Name of the SageMaker endpoint with Deepgram TTS model deployed.
</ParamField>

<ParamField path="region" type="str" required>
  AWS region where the SageMaker endpoint is deployed (e.g., `"us-east-2"`).
</ParamField>

<ParamField path="voice" type="str" default="aura-2-helena-en" deprecated>
  Voice model to use for synthesis. *Deprecated in v0.0.105. Use
  `settings=DeepgramSageMakerTTSService.Settings(voice=...)` instead.*
</ParamField>

<ParamField path="settings" type="DeepgramSageMakerTTSService.Settings" default="None">
  Runtime-configurable settings. See [DeepgramSageMakerTTSService
  Settings](#deepgramsagemakerttsservice-settings) below.
</ParamField>

<ParamField path="sample_rate" type="int" default="None">
  Output audio sample rate in Hz. When `None`, uses the pipeline's configured
  sample rate.
</ParamField>

<ParamField path="encoding" type="str" default="linear16">
  Audio encoding format.
</ParamField>

#### 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](/pipecat/fundamentals/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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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",
    ),
)
```

<Tip>
  The `InputParams` / `params=` pattern is deprecated as of v0.0.105. Use
  `Settings` / `settings=` instead. See the [Service Settings
  guide](/pipecat/fundamentals/service-settings) for migration details.
</Tip>

## 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](https://developers.deepgram.com/docs/deploy-amazon-sagemaker) for setup instructions.

## Event Handlers

The WebSocket and SageMaker services support the standard [service connection events](/api-reference/server/events/service-events):

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

```python theme={null}
@tts.event_handler("on_connected")
async def on_connected(service):
    print("Connected to Deepgram")
```