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

# Pipecat

> Use Gradium streaming text-to-speech in Pipecat voice agents

Pipecat is a framework for building real-time voice and multimodal agents. Its `GradiumTTSService` lets a Pipecat pipeline stream synthesized speech through Gradium's WebSocket API.

<CardGroup cols={2}>
  <Card title="Pipecat Gradium reference" icon="code" href="https://reference-server.pipecat.ai/en/latest/api/pipecat.services.gradium.tts.html">
    API reference for `GradiumTTSService`.
  </Card>

  <Card title="Gradium voice example" icon="play" href="https://github.com/pipecat-ai/pipecat/blob/main/examples/voice/voice-gradium.py">
    Complete Pipecat example using Gradium services.
  </Card>

  <Card title="Gradient Bang" icon="github" href="https://github.com/pipecat-ai/gradient-bang">
    Pipecat's multiplayer game, using Gradium for TTS by default.
  </Card>

  <Card title="Gradium TTS guide" icon="book" href="/guides/text-to-speech">
    Gradium WebSocket TTS setup and streaming behavior.
  </Card>
</CardGroup>

## Installation

Install Pipecat with the Gradium extra:

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

Set your Gradium API key in the environment:

```bash theme={null}
export GRADIUM_API_KEY=gd_your_api_key_here
```

## Basic setup

Create a `GradiumTTSService` with your API key and a Gradium voice ID. Pipecat's current pattern is to pass runtime options through `GradiumTTSService.Settings(...)`.

```python theme={null}
import os

from pipecat.services.gradium.tts import GradiumTTSService

tts = GradiumTTSService(
    api_key=os.environ["GRADIUM_API_KEY"],
    settings=GradiumTTSService.Settings(
        voice="YTpq7expH9539ERJ",
    ),
)
```

Then place the service in the audio pipeline after the LLM and before the transport output:

```python theme={null}
pipeline = Pipeline(
    [
        transport.input(),
        stt,
        user_aggregator,
        llm,
        tts,
        transport.output(),
        assistant_aggregator,
    ]
)
```

## Configuration

Common settings:

| Setting             | Type              | Description                                              |
| ------------------- | ----------------- | -------------------------------------------------------- |
| `api_key`           | `str`             | Gradium API key.                                         |
| `settings.voice`    | `str`             | Gradium voice ID to synthesize with.                     |
| `settings.model`    | `str`             | Optional Gradium model name.                             |
| `settings.language` | `Language \| str` | Optional synthesis language.                             |
| `url`               | `str`             | Optional Gradium WebSocket endpoint override.            |
| `json_config`       | `str`             | Optional JSON string for additional model configuration. |

<Note>
  Gradium TTS in Pipecat outputs audio at 48kHz. Pipecat sets this sample rate automatically.
</Note>

## Runtime behavior

* **Streaming audio**: Gradium emits audio over a WebSocket, which Pipecat forwards through the active transport.
* **Word timestamps**: Gradium timestamp events can support synchronized text display.
* **Voice switching**: Updating the `voice` setting at runtime reconnects the Gradium WebSocket with the new voice.
* **Connection events**: `on_connected`, `on_disconnected`, and `on_connection_error` are available for logging and health checks.

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

## Example project

[Gradient Bang](https://github.com/pipecat-ai/gradient-bang) is Pipecat's multiplayer game and uses Gradium as the default TTS provider. Its bot environment includes `TTS_PROVIDER=gradium`, making it a useful larger reference for a real voice-agent application built on Pipecat.