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.

Gradium TTS API Reference

Pipecat’s API methods for Gradium TTS integration

Example Implementation

Complete example with streaming synthesis

Gradium Documentation

Official Gradium TTS API documentation

Gradium Platform

Access API keys and voice library

Installation

To use Gradium services, install the required dependencies:

pip install "pipecat-ai[gradium]"

Prerequisites

Gradium Account Setup

Before using Gradium TTS services, you need:

1. Gradium Account: Sign up at Gradium
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

api_key · str · required

Gradium API key for authentication.

voice_id · str · default: "YTpq7expH9539ERJ" · deprecated

Voice identifier. Deprecated in v0.0.105. Use settings=GradiumTTSService.Settings(voice=...) instead.

url · str · default: "wss://eu.api.gradium.ai/api/speech/tts"

Gradium WebSocket API endpoint.

model · str · default: "default" · deprecated

Model ID to use for synthesis. Deprecated in v0.0.105. Use settings=GradiumTTSService.Settings(model=...) instead.

json_config · str · default: "None"

Optional JSON configuration string for additional model settings.

params · InputParams · default: "None" · deprecated

Deprecated in v0.0.105. Use settings=GradiumTTSService.Settings(...) instead.

settings · GradiumTTSService.Settings · default: "None"

Runtime-configurable settings. See Settings below.

Settings

Runtime-configurable settings passed via the settings constructor argument using GradiumTTSService.Settings(...). These can be updated mid-conversation with TTSUpdateSettingsFrame. See 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.)

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

Usage

Basic Setup

from pipecat.services.gradium import GradiumTTSService

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

With Custom Configuration

tts = GradiumTTSService(
    api_key=os.getenv("GRADIUM_API_KEY"),
    settings=GradiumTTSService.Settings(
        model="default",
        voice="your-voice-id",
    ),
)

The InputParams / params= pattern is deprecated as of v0.0.105. Use Settings / settings= instead. See the Service Settings guide for migration details.

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:

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

@tts.event_handler("on_connected")
async def on_connected(service):
    print("Connected to Gradium")