Gradium TTS

Overview

Gradium text-to-speech is available in LiveKit Agents through LiveKit Inference and the Gradium plugin. With LiveKit Inference, your agent runs on LiveKit's infrastructure to minimize latency. No separate provider API key is required, and usage and rate limits are managed through LiveKit Cloud. Use the plugin instead if you want to manage your own billing and rate limits. Pricing for LiveKit Inference is available on the pricing page .

Gradium streams natural-sounding speech in English, French, German, Spanish, and Portuguese, with regional accent coverage in each language. Built-in text normalization handles the hard cases like phone numbers, dates, alphanumeric codes, and URLs that voice agents hit constantly. See Customizing pronunciation .

LiveKit Inference

Use LiveKit Inference to access Gradium TTS without a separate Gradium API key.

Usage

To use Gradium, use the TTS class from the inference module:

from livekit.agents import AgentSession, inference

session = AgentSession(
    tts=inference.TTS(
        model="gradium/default",
        voice="4SZHfMpw-p46Ywgs",
        language="en"
    ),
    # ... llm, stt, vad, turn_handling, etc.
)

import { AgentSession, inference } from '@livekit/agents';

const session = new AgentSession({
    tts: new inference.TTS({
        model: "gradium/default",
        voice: "4SZHfMpw-p46Ywgs",
        language: "en" 
    }),
    // ... llm, stt, vad, turnHandling, etc.
});

Parameters

Model parameters

Pass the following parameters inside extra_kwargs (Python) or modelOptions (Node.js):

To learn more, see Voice settings  in the Gradium docs.

Voices

LiveKit Inference supports all of the flagship voices available in the Gradium API. Alongside standard American, British, and Irish English, the catalog includes regional accents like Québécois French, Bavarian, Austrian German, Castilian, Mexican Spanish, and Brazilian and European Portuguese so you can match a voice to the region and accent your agent serves. Explore the available voices in the Gradium voice library , and use the voice by copying its ID into your LiveKit agent session.

The following is a small sample of the Gradium voices available in LiveKit Inference.

String descriptors

As a shortcut, you can also pass a descriptor with the model ID and voice directly to the tts argument in your AgentSession:

from livekit.agents import AgentSession

session = AgentSession(
    tts="gradium/default:4SZHfMpw-p46Ywgs",
    # ... llm, stt, vad, turn_handling, etc.
)

import { AgentSession } from '@livekit/agents';

const session = new AgentSession({
    tts: "gradium/default:4SZHfMpw-p46Ywgs",
    // ... tts, stt, vad, turnHandling, etc.
});

Plugin

This plugin allows you to use Gradium  as a TTS provider for your voice agents.

Installation

Install the plugin from PyPI:

pip install "livekit-agents[gradium]~=1.6"

Authentication

The Gradium plugin requires a Gradium API key .

Set GRADIUM_API_KEY in your .env file.

Usage

Use Gradium TTS within an AgentSession or as a standalone speech generator. For example, you can use this TTS in the Voice AI quickstart.

from livekit.plugins import gradium

session = AgentSession(
    tts=gradium.TTS(),
    # ... llm, stt, etc.
)

Parameters

This section describes some of the available parameters. See the plugin reference for a complete list of all available parameters.

Customizing pronunciation

Gradium supports two approaches for controlling how specific text is spoken. To learn more, see Text rewriting rules  and Voice settings  in the Gradium docs.

Text rewriting rules

Voice agents spend much of their time reading back text that was never written to be spoken: phone numbers, dates, order codes, number plates, and email addresses. Gradium normalizes these before synthesis, so the LLM does not have to spell them out. Pass a language code to rewrite_rules to enable the rules for that language:

from livekit.agents import AgentSession, inference

session = AgentSession(
    tts=inference.TTS(
        model="gradium/default",
        voice="4SZHfMpw-p46Ywgs",
        extra_kwargs={
            "rewrite_rules": "en",
        },
    ),
    # ... llm, stt, vad, turn_handling, etc.
)

import { AgentSession, inference } from '@livekit/agents';

const session = new AgentSession({
    tts: new inference.TTS({
        model: "gradium/default",
        voice: "4SZHfMpw-p46Ywgs",
        modelOptions: {
            rewrite_rules: "en",
        },
    }),
    // ... llm, stt, vad, turnHandling, etc.
});

Presets are available for each supported language: en, fr, de, es, and pt. To apply a subset instead of a whole preset, pass a comma-separated list of individual rule names. For the current rules and what each one covers, see Text rewriting rules  in the Gradium docs.

Pronunciation dictionaries

Create a reusable pronunciation dictionary in Gradium for brand names, product names, and domain-specific terms, then pass its ID in pronunciation_id. Each rule maps a written form to the way it should be spoken. For example, a rule can rewrite "Gradium" as "Grey-dee-um". The dictionary applies for the whole session, so every mention is consistent. Use this when you have many terms or want to share pronunciations across agents. Create and manage dictionaries in Gradium Studio  or with the pronunciations API .

Additional resources

The following resources provide more information about using Gradium with LiveKit Agents.

Python package

The livekit-plugins-gradium package on PyPI.

Plugin reference

Reference for the Gradium TTS plugin.

GitHub repo

View the source or contribute to the LiveKit Gradium TTS plugin.

Voice AI quickstart

Get started with LiveKit Agents and Gradium TTS.

Gradium docs

Gradium API documentation.

Gradium STT

Guide to the Gradium STT plugin with LiveKit Agents.