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

# AssemblyAI Text-to-Speech

> TTS with AssemblyAITTSService, streaming speech synthesis over AssemblyAI's WebSocket API with per-word timings for voice agents.

## Overview

`AssemblyAITTSService` streams text to AssemblyAI's Streaming TTS WebSocket API and plays the audio as it arrives. Per-word timings drive word-level text output, and interruptions cancel synthesis in flight without reconnecting.

> [card] [AssemblyAI TTS API Reference](https://reference-server.pipecat.ai/en/latest/api/pipecat.services.assemblyai.tts.html)
>
> Pipecat's API methods for AssemblyAI TTS integration

> [card] [Example Implementation](https://github.com/pipecat-ai/pipecat/blob/main/examples/voice/voice-assemblyai.py)
>
> Complete example with AssemblyAI STT and TTS

> [card] [AssemblyAI Documentation](https://www.assemblyai.com/docs)
>
> Official AssemblyAI documentation

> [card] [AssemblyAI Dashboard](https://www.assemblyai.com/dashboard)
>
> Manage API keys and cloned voices

## Installation

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

## Prerequisites

### AssemblyAI Account Setup

1. **AssemblyAI Account**: Sign up at the [AssemblyAI dashboard](https://www.assemblyai.com/dashboard)
2. **API Key**: Generate an API key from the dashboard

### Required Environment Variables

* `ASSEMBLYAI_API_KEY`: Your AssemblyAI API key for authentication

## Configuration

### AssemblyAITTSService

**api\_key** `str` *required*

AssemblyAI API key. A temporary token opens a single session, so it can't
carry the service's reconnects and session renewals.

**url** `str` (default: wss\://tts.us.assemblyai.com/v1/ws)

Streaming TTS WebSocket URL. Use `wss://tts.eu.assemblyai.com/v1/ws` to
process text and audio in the EU. A cloned voice works only on the host of the
zone it was created in.

**sample\_rate** `int` (default: None)

Output sample rate in Hz. When `None`, uses the pipeline's output sample rate.

**settings** `AssemblyAITTSService.Settings` (default: None)

Runtime-configurable settings. See [Settings](#settings) below.

### Settings

Runtime-configurable settings passed via the `settings` constructor argument using `AssemblyAITTSService.Settings(...)`. These can be updated mid-conversation with `TTSUpdateSettingsFrame`. Changing `voice`, `language`, or `model` reconnects the session. See [Service Settings](https://docs.pipecat.ai/pipecat/fundamentals/service-settings.md) for details.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `voice` | `str` | `"49c443a4-8a1d-5f7e-b70b-98bdbd9823c3"` | Voice to speak with, sent as the API's `voice_id`. Accepts a voice ID, an AssemblyAI library slug such as `aai-jane`, or the slug of a cloned voice shown in the dashboard. Default is Audrey. |
| `language` | `Language \| str` | `None` | Language the session speaks. When unset, the session speaks the voice's own language. |
| `model` | `str` | `None` | Model name, such as `assemblyai-tts-1`. When unset, the session runs the language's default model. |

## Usage

### Basic Setup

```python theme={null}
import os

from pipecat.services.assemblyai.tts import AssemblyAITTSService

tts = AssemblyAITTSService(
    api_key=os.getenv("ASSEMBLYAI_API_KEY"),
)
```

### Choosing a Voice

```python theme={null}
tts = AssemblyAITTSService(
    api_key=os.getenv("ASSEMBLYAI_API_KEY"),
    settings=AssemblyAITTSService.Settings(voice="aai-jane"),
)
```

### Processing Data in the EU

```python theme={null}
tts = AssemblyAITTSService(
    api_key=os.getenv("ASSEMBLYAI_API_KEY"),
    url="wss://tts.eu.assemblyai.com/v1/ws",
)
```

## Notes

* **Sentence and token aggregation**: With sentence aggregation, each sentence is its own request. With `TextAggregationMode.TOKEN`, the turn's text streams as it is generated.
* **Word timestamps**: Per-word timings produce word-level `TTSTextFrame` output.
* **Sessions**: The service keeps an idle session open, replaces a session before its one-hour limit, and waits as long as the server asks before reconnecting.

## Event Handlers

`AssemblyAITTSService` supports the standard [service connection events](https://docs.pipecat.ai/api-reference/server/events/service-events.md):

| Event | Description |
| - | - |
| `on_connected` | Connected to AssemblyAI WebSocket |
| `on_disconnected` | Disconnected from AssemblyAI |
| `on_connection_error` | WebSocket connection error occurred |

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.