tts-cache-router docs

LiveKit Agents

OpenAI with LiveKit

OpenAI in a LiveKit agent: through our plugin, or through LiveKit's OpenAI plugin with a changed URL.

With our plugin#

OpenAI with the settings of OpenAI's own LiveKit plugin. OpenAI speaks the language of the text, at 24000 Hz.

pip install livekit-plugins-tts-cache-router
agent.py
from livekit.plugins import tts_cache_router as tcr# The API key comes from TTS_CACHE_ROUTER_API_KEY.tts = tcr.TTS(    provider=tcr.OpenAI(        model="gpt-4o-mini-tts",        voice="ash",    ),)

Pass tts to AgentSession(tts=tts). Set TTS_CACHE_ROUTER_API_KEY in the agent’s environment, and store your OpenAI key under Provider keys. The constructor of TTS itself is on the plugin’s page.

tcr.OpenAI(...)#

modelstrDefault "gpt-4o-mini-tts"
gpt-4o-mini-tts, gpt-4o-mini-tts-2025-12-15, tts-1 or tts-1-hd.
voicestrDefault "ash"
An OpenAI voice. tts-1 and tts-1-hd have alloy, ash, coral, echo, fable, nova, onyx, sage and shimmer; gpt-4o-mini-tts also ballad, verse, marin and cedar.
speedfloatDefault 1.0
Speech speed, 0.25–4.0.
instructionsstr | NoneDefault None
How to speak: tone, accent, emotion, pace. gpt-4o-mini-tts follows them; tts-1 and tts-1-hd ignore them.

Every value the router accepts, and the languages per model, are in Models and options.

Changing settings#

Replies that start afterwards use the new settings:

Python
tts.update_options(instructions="Speak calmly and slowly.")

With LiveKit's OpenAI plugin#

Keep livekit-plugins-openai and point it at the router: your router API key in place of your OpenAI key, and the router’s address. Nothing else changes.

pip install livekit-plugins-openai
agent.py
import osfrom livekit.plugins import openaitts = openai.TTS(    model="gpt-4o-mini-tts",    voice="ash",    api_key=os.environ["TTS_CACHE_ROUTER_API_KEY"],    base_url="https://api.ttscacherouter.dev/openai/v1",)

base_url ends in /v1, as OpenAI’s own does. The plugin doesn’t stream text, so an AgentSession sends it one sentence at a time, and each sentence is cached on its own.

Requests, responses and errors keep OpenAI’s own shape. The endpoints behind it are described in OpenAI API drop-in.

Which to choose#

Both use your org's cache and your stored provider key, and sound the same.

  • Our plugin reports only the characters OpenAI billed in LiveKit’s TTSMetrics (cache hits count zero), and lets you switch provider with update_options.
  • OpenAI’s plugin is the smallest change to an agent that already uses it. Its metrics count every character, cached or not; the dashboard’s Usage page has the real split.