Baseten TTS plugin guide | LiveKit Documentation

Available inPython

Overview

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

Installation

Install the plugin from PyPI:

uv add "livekit-agents[baseten]~=1.6"

Authentication

The Baseten plugin requires a Baseten API key .

Set the following in your .env file:

BASETEN_API_KEY=<your-baseten-api-key>

Model deployment

You must deploy a TTS model to Baseten to use it with LiveKit Agents. The plugin supports two model families, selected with the model parameter:

`model`	Deployment	Notes
`orpheus` (default)	Orpheus	Preset voices such as `tara`. HTTP or websocket.
`qwen3-tts`	Qwen3-TTS 12Hz Base Streaming, 0.6B or 1.7B	Requires a websocket endpoint. Voices are clones that you register.

The two families use different wire protocols and aren't interchangeable, so set model to match the deployment you created. Your deployment includes a private model endpoint URL to provide to the LiveKit Agents integration.

Baseten model endpoints come in two forms, HTTP and websocket.

For orpheus, the plugin selects its mode from the URL scheme:

https:// endpoints use HTTP synthesis. The agent sends the full text in a single request and receives the audio in the response.
wss:// endpoints use websocket streaming. The agent streams words to the model as the LLM generates them, and the model streams audio back as it produces it. This significantly reduces latency for voice agents. Streaming requires a websocket-capable Baseten TTS deployment .

When model_endpoint starts with wss://, the plugin reports capabilities.streaming=True and the agent uses streaming synthesis. Otherwise the plugin falls back to HTTP synthesis. No further configuration is needed to switch between the two.

qwen3-tts is websocket only. It also accepts model_id or chain_id, which build the endpoint URL for you.

Usage

Use Baseten 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 baseten

session = AgentSession(
   # Pass a wss:// URL for websocket streaming, or an https:// URL for HTTP synthesis.
   tts=baseten.TTS(
      model_endpoint="<your-model-endpoint>",
      voice="tara",
   )
   # ... llm, stt, etc.
)

To use Qwen3-TTS instead, set model and name a registered voice clone:

tts=baseten.TTS(model="qwen3-tts", model_id="<your-model-id>", voice="<your-voice>")

Qwen3-TTS voices

The Qwen3-TTS Base checkpoint ships no built-in speakers, so there's no equivalent of the Orpheus tara voice. Register a clone from 10 to 20 seconds of clean speech, then pass its name as voice:

from livekit.plugins.baseten import register_voice

await register_voice(
    model_endpoint="wss://model-<id>.api.baseten.co/environments/production/websocket",
    name="my_voice",
    ref_audio_path="./reference.wav",
    ref_text="Transcript of the reference audio.",
)

Use list_voices to see which voices a replica currently has.

The server stores uploaded voices on the container's local disk, so a voice registered at runtime lives on one replica and is lost when that container restarts. For anything beyond single-replica testing, bake the reference audio into the deployment with REQUIRED_VOICES, or pass ref_audio and ref_text to clone inline on each session.

Parameters

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

modelTTSModelsDefault: orpheus

Which deployment protocol to use: orpheus or qwen3-tts. The two aren't interchangeable. See Model deployment.

model_endpointstringEnv: BASETEN_MODEL_ENDPOINT

The endpoint URL for your deployed model, found in your Baseten dashboard. Pass a wss:// URL to enable realtime websocket streaming, or an https:// URL for HTTP synthesis. HTTP synthesis is orpheus only.

model_idstring

Baseten truss model ID. The plugin builds the websocket endpoint URL for you. qwen3-tts only. For orpheus, pass model_endpoint.

chain_idstring

Baseten chain ID. The plugin builds the websocket endpoint URL for you. qwen3-tts only. For orpheus, pass model_endpoint.

voicestring

The voice to use for speech synthesis. Defaults to tara for orpheus. Required for qwen3-tts, where it names a registered voice clone.

languageLanguageCode

Language code for the output audio. Defaults to en for orpheus and Auto for qwen3-tts.

temperaturefloatDefault: 0.6

Controls the randomness of the generated speech. Higher values make the output more random. orpheus only.

max_tokensintDefault: 2000

Maximum number of tokens to generate per request. orpheus websocket synthesis only.

buffer_sizeintDefault: 10

Number of words per chunk streamed to the model. Smaller values reduce time-to-first-audio at the cost of slightly more overhead. orpheus websocket synthesis only.

word_timestampsboolDefault: False

Forward word-level alignment to LiveKit as a timed transcript. qwen3-tts only.

The following parameters apply to qwen3-tts only. See the plugin reference for details:

task_type: Base for the voice-cloning checkpoint; CustomVoice and VoiceDesign deployments expose preset speaker names.
instructions: Style prompt for CustomVoice and VoiceDesign deployments.
max_new_tokens: Cap on audio tokens per sentence.
initial_codec_chunk_frames: First-chunk size. Larger values trade time-to-first-audio for onset quality.
x_vector_only_mode: Condition on the speaker embedding alone and skip in-context learning from the reference.
ref_audio and ref_text: Reference clip for inline cloning, as an HTTP URL or local path, plus its transcript.
extra_config: Merged into session.config last.

Additional resources

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

Python package

The livekit-plugins-baseten package on PyPI.

Plugin reference

Reference for the Baseten TTS plugin.

GitHub repo

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

Baseten docs

Baseten's full docs site.

Voice AI quickstart

Get started with LiveKit Agents and Baseten.

Baseten STT

Guide to the Baseten STT plugin with LiveKit Agents.