tts-cache-router docs

LiveKit Agents

Cartesia with LiveKit

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

View as Markdown

With our plugin#

Cartesia’s Sonic voices with the settings of LiveKit’s Cartesia plugin. TTS’s sample_rate is 8000, 16000, 22050, 24000, 44100 or 48000.

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.Cartesia(        model="sonic-3",        voice="f786b574-daa5-4673-aa0c-cbe3e8534c02",        language="en",    ),)

Pass tts to AgentSession(tts=tts). Set TTS_CACHE_ROUTER_API_KEY in the agent’s environment, and store your Cartesia key under Provider keys. TTS’s own arguments are on the plugin’s page.

tcr.Cartesia(...)#

modelstrDefault "sonic-3"
"sonic-3.6", "sonic-3.5" or "sonic-3", or a dated snapshot of one, e.g. "sonic-3.6-2026-08-27".
voicestrDefault "f786b574-daa5-4673-aa0c-cbe3e8534c02"
A Cartesia voice id, from Cartesia’s library or your own voices. The default is Katie, as in LiveKit’s plugin.
languagestrDefault "en"
The language of the text, e.g. "en" or "hi" ("en-GB" is sent as "en", as LiveKit’s plugin sends it). The languages differ by model.
speedfloat | NoneDefault None
Speaking rate, 0.6–1.5. None: Cartesia’s default (1.0).
emotionstr | list[str] | NoneDefault None
Guide the delivery (English), e.g. "calm", "sad" or "angry"; a list uses its first, as LiveKit’s plugin does. None: Cartesia reads the emotion from the text.
volumefloat | NoneDefault None
Loudness, 0.5–2.0. None: Cartesia’s default (1.0).
pronunciation_dict_idstr | NoneDefault None
A Cartesia pronunciation dictionary’s id. Sentences cached before you edit the dictionary keep their audio until your cache retention expires them.
word_timestampsboolDefault True
Word-by-word transcripts from Cartesia's word timings.

Every accepted value, and the languages per model: Models and options.

Changing settings#

Replies that start afterwards use the new settings:

Python
tts.update_options(emotion="calm", speed=1.1)

With LiveKit's Cartesia plugin#

Keep livekit-plugins-cartesia and point it at the router: your router API key in place of your Cartesia key, and the router’s address.

pip install livekit-plugins-cartesia
agent.py
import osfrom livekit.plugins import cartesiatts = cartesia.TTS(    model="sonic-3",    voice="f786b574-daa5-4673-aa0c-cbe3e8534c02",    language="en",    api_key=os.environ["TTS_CACHE_ROUTER_API_KEY"],    base_url="https://api.ttscacherouter.dev/cartesia",)

base_url is the only URL to change: the plugin derives its WebSocket URL from it. Streaming, synthesize() and word timestamps work as before.

The router splits the reply into sentences and synthesizes each on its own, through either plugin: each sentence is a take of its own rather than a continuation of the one before, and the pauses between sentences are shorter than in one Cartesia context. When the user interrupts, the sentence being synthesized finishes at Cartesia and is cached; the rest of the reply isn’t sent. The other differences from Cartesia’s own messages are on Cartesia API drop-in.

Requests, responses and errors keep Cartesia’s own shape; the endpoints are on Cartesia 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 Cartesia billed in TTSMetrics (cache hits count zero), and switches provider with update_options.
  • Cartesia’s plugin is the smallest change to an agent that already uses it. Its metrics count every character, cached or not; Usage has the real split.