tts-cache-router docs

LiveKit Agents

ElevenLabs with LiveKit

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

With our plugin#

ElevenLabs with the settings of ElevenLabs' own LiveKit plugin. eleven_v3 and eleven_v4 models go through ElevenLabs' text-to-dialogue API, as that plugin sends them.

pip install livekit-plugins-tts-cache-router
agent.py
from livekit.plugins import tts_cache_router# The API key comes from TTS_CACHE_ROUTER_API_KEY.tts = tts_cache_router.TTS(    provider=tts_cache_router.ElevenLabs(        voice_id="JBFqnCBsd6RMkjVDRZzb",        model="eleven_flash_v2_5",    ),)

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

tts_cache_router.ElevenLabs(...)#

voice_idstrRequired
An ElevenLabs voice id from your voice library.
modelstrDefault "eleven_turbo_v2_5"
eleven_flash_v2_5, eleven_turbo_v2_5, eleven_multilingual_v2, eleven_flash_v2, eleven_turbo_v2, eleven_v3, eleven_v3_conversational, eleven_v4 or eleven_v4_turbo.
languagestr | NoneDefault None
A language to enforce, e.g. "en" ("en-US" is sent as "en", as ElevenLabs’ plugin sends it). None: ElevenLabs detects it.
voice_settingsVoiceSettings | NoneDefault None
VoiceSettings(stability, similarity_boost, style=None, speed=None, use_speaker_boost=None): stability, similarity and style 0–1, speed 0.7–1.2. None: the voice’s stored settings, which the router re-reads about once a minute. Dialogue models (eleven_v3, eleven_v4) use stability only.
apply_text_normalizationstrDefault "auto"
"auto", "on" or "off": spell out numbers, dates and the like before speaking.
apply_language_text_normalizationbool | NoneDefault None
Language-specific normalization (Japanese); adds latency.
enable_ssml_parsingboolDefault False
Parse SSML tags in the text.
enable_loggingboolDefault True
False uses ElevenLabs’ zero-retention mode (enterprise accounts).
pronunciation_dictionary_locatorslist[PronunciationDictionaryLocator]Default ()
Up to 3 PronunciationDictionaryLocator(pronunciation_dictionary_id, version_id).
sync_alignmentboolDefault True
Word-by-word transcripts from ElevenLabs' character timings.
preferred_alignmentstr | NoneDefault None
Word timings of the text as sent ("original") or as ElevenLabs normalized it ("normalized"). None: original for Japanese, Korean and Chinese, normalized otherwise.

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(    voice_settings=tts_cache_router.VoiceSettings(stability=0.4, similarity_boost=0.8, speed=1.1),)

With LiveKit's ElevenLabs plugin#

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

pip install livekit-plugins-elevenlabs
agent.py
import osfrom livekit.plugins import elevenlabstts = elevenlabs.TTS(    voice_id="JBFqnCBsd6RMkjVDRZzb",    model="eleven_flash_v2_5",    api_key=os.environ["TTS_CACHE_ROUTER_API_KEY"],    base_url="https://api.ttscacherouter.dev/elevenlabs/v1",)

base_url ends in /v1, as ElevenLabs’ own does. Streaming (the multi-context WebSocket), synthesize(), word-aligned transcripts, eleven_v3 and eleven_v4 through text-to-dialogue, and list_voices() all work as before.

Requests, responses and errors keep ElevenLabs’s own shape. The endpoints behind it are described in ElevenLabs 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 ElevenLabs billed in LiveKit’s TTSMetrics (cache hits count zero), and lets you switch provider with update_options.
  • ElevenLabs’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.