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.

LiveKit Agents is a framework for realtime voice AI over WebRTC, SIP, and streaming media. The Gradium plugin lets a LiveKit agent use Gradium for speech-to-text, text-to-speech, or both inside the same AgentSession.

Gradium TTS plugin

LiveKit’s guide to Gradium text-to-speech.

Gradium STT plugin

LiveKit’s guide to Gradium speech-to-text.

Plugin reference

Python API reference for livekit.plugins.gradium.

Gradium guide

End-to-end Gradium and LiveKit voice agent walkthrough.

​
Install

Install LiveKit Agents with the Gradium plugin extra: 
pip install "livekit-agents[gradium]~=1.5"
Set the required credentials in your environment: 
export LIVEKIT_URL=wss://your-project.livekit.cloud
export LIVEKIT_API_KEY=your-livekit-api-key
export LIVEKIT_API_SECRET=your-livekit-api-secret
export GRADIUM_API_KEY=gd_your_api_key_here

​
Basic agent session

Use gradium.STT() to transcribe user audio and gradium.TTS() to synthesize agent replies. 
from livekit.agents import AgentSession
from livekit.plugins import gradium

session = AgentSession(
    stt=gradium.STT(),
    tts=gradium.TTS(
        voice_id="YTpq7expH9539ERJ",
    ),
    # ... llm, vad, tools, and other session options
)
You can also use only one side of Gradium. For example, keep an existing STT provider and use Gradium just for speech output: 
session = AgentSession(
    tts=gradium.TTS(),
    # ... llm, stt, etc.
)

​
Configuration

Common Gradium options in LiveKit Agents:
SettingApplies toDescription
api_keySTT, TTSGradium API key. Defaults to GRADIUM_API_KEY.
model_endpointSTT, TTSGradium WebSocket endpoint. Use the US endpoint when you need US-region routing.
model_nameSTT, TTSGradium model name. Defaults to default.
voice_idTTSGradium voice ID for synthesized replies. Defaults to Emma.
pronunciation_idTTSOptional Gradium pronunciation dictionary ID.
json_configTTSAdvanced TTS settings such as speed and rewrite rules.
vad_thresholdSTTSemantic VAD threshold for detecting when the user has finished speaking.
vad_bucketSTTSemantic VAD timing bucket.

​
Custom pronunciation

Pass a Gradium pronunciation dictionary ID into the TTS plugin when an agent needs brand names, product names, or domain-specific terms spoken consistently. 
tts = gradium.TTS(
    voice_id="YTpq7expH9539ERJ",
    pronunciation_id="pronunciation_dictionary_id",
)
For lower-level pronunciation and rewrite behavior, see Pronunciation Dictionaries and Voice Settings.

​
When to use LiveKit with Gradium

  • Realtime voice agents: run a complete STT, LLM, and TTS loop in AgentSession.
  • WebRTC applications: connect browser and mobile users to Gradium-powered speech through LiveKit rooms.
  • Telephony agents: use LiveKit SIP while keeping Gradium as the speech model layer.
  • Production deployments: deploy LiveKit agents with managed rooms, credentials, and worker processes.