Pipecat

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.

Pipecat Gradium reference

API reference for GradiumTTSService.

Gradium voice example

Complete Pipecat example using Gradium services.

Gradient Bang

Pipecat’s multiplayer game, using Gradium for TTS by default.

Gradium TTS guide

Gradium WebSocket TTS setup and streaming behavior.

Installation

Install Pipecat with the Gradium extra:

uv add "pipecat-ai[gradium]"

Set your Gradium API key in the environment:

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(...).

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:

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.

Gradium TTS in Pipecat outputs audio at 48kHz. Pipecat sets this sample rate automatically.

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.

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

Example project

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.

Introduction

Agent Frameworks

Tools

Pipecat Gradium reference

Gradium voice example

Gradient Bang

Gradium TTS guide

Installation

Basic setup

Configuration

Runtime behavior

Example project

Pipecat Gradium reference

Gradium voice example

Gradient Bang

Gradium TTS guide

​Installation

​Basic setup

​Configuration

​Runtime behavior

​Example project

Installation

Basic setup

Configuration

Runtime behavior

Example project