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

# Gradium

> Text-to-speech service using Gradium's low-latency streaming API

## Overview

`GradiumTTSService` provides high-quality text-to-speech synthesis using Gradium's WebSocket API with expressive voices, instant voice cloning, streaming inference for real-time applications, and multilingual support.

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

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

  <Card title="Gradium Documentation" icon="book" href="https://gradium.ai/api_docs.html#tag/TTS">
    Official Gradium TTS API documentation
  </Card>

  <Card title="Gradium Platform" icon="microphone" href="https://gradium.ai/">
    Access API keys and voice library
  </Card>
</CardGroup>

## Installation

To use Gradium services, install the required dependencies:

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

## Prerequisites

### Gradium Account Setup

Before using Gradium TTS services, you need:

1. **Gradium Account**: Sign up at [Gradium](https://gradium.ai/)
2. **API Key**: Generate an API key from your account dashboard
3. **Voice Selection**: Choose voice IDs from the Gradium platform or create custom voices

### Required Environment Variables

* `GRADIUM_API_KEY`: Your Gradium API key for authentication

## Configuration

### GradiumTTSService

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

<ParamField path="voice_id" type="str" default="YTpq7expH9539ERJ" deprecated>
  Voice identifier. *Deprecated in v0.0.105. Use
  `settings=GradiumTTSService.Settings(voice=...)` instead.*
</ParamField>

<ParamField path="url" type="str" default="wss://eu.api.gradium.ai/api/speech/tts">
  Gradium WebSocket API endpoint.
</ParamField>

<ParamField path="model" type="str" default="default" deprecated>
  Model ID to use for synthesis. *Deprecated in v0.0.105. Use
  `settings=GradiumTTSService.Settings(model=...)` instead.*
</ParamField>

<ParamField path="json_config" type="str" default="None">
  Optional JSON configuration string for additional model settings.
</ParamField>

<ParamField path="params" type="InputParams" default="None" deprecated>
  *Deprecated in v0.0.105. Use `settings=GradiumTTSService.Settings(...)`
  instead.*
</ParamField>

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

### Settings

Runtime-configurable settings passed via the `settings` constructor argument using `GradiumTTSService.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.)* |

<Note>
  The Gradium service outputs audio at a fixed 48kHz sample rate. This is set
  automatically and cannot be changed.
</Note>

## Usage

### Basic Setup

```python theme={null}
from pipecat.services.gradium import GradiumTTSService

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

### With Custom Configuration

```python theme={null}
tts = GradiumTTSService(
    api_key=os.getenv("GRADIUM_API_KEY"),
    settings=GradiumTTSService.Settings(
        model="default",
        voice="your-voice-id",
    ),
)
```

<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

* **Word timestamps**: Gradium provides word-level timestamps for synchronized text display.
* **Voice switching**: Changing the voice at runtime via `UpdateSettingsFrame` automatically disconnects and reconnects the WebSocket with the new voice configuration.
* **Fixed sample rate**: Gradium always outputs at 48kHz. The sample rate is not configurable.

## Event Handlers

Gradium TTS supports the standard [service connection events](/api-reference/server/events/service-events):

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

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