Skip to main content

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 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:
SettingTypeDescription
api_keystrGradium API key.
settings.voicestrGradium voice ID to synthesize with.
settings.modelstrOptional Gradium model name.
settings.languageLanguage | strOptional synthesis language.
urlstrOptional Gradium WebSocket endpoint override.
json_configstrOptional 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.