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"

Voice identifier.

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

Gradium WebSocket API endpoint.

model · str · default: "default"

Model ID to use for synthesis.

json_config · str · default: "None"

Optional JSON configuration string for additional model settings.

params · InputParams · default: "None"

Runtime-configurable generation settings. See InputParams below.

InputParams

Generation settings that can be set at initialization via the params constructor argument.

Parameter	Type	Default	Description
temp	float	0.6	Temperature for generation.

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"),
    voice_id="YTpq7expH9539ERJ",
)

With Custom Configuration

tts = GradiumTTSService(
    api_key=os.getenv("GRADIUM_API_KEY"),
    voice_id="your-voice-id",
    model="default",
    params=GradiumTTSService.InputParams(
        temp=0.8,
    ),
)

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")