Best Live Avatar
Add model ↗

LiveKit avatar integration with LemonSlice

Add LemonSlice video to an existing Python LiveKit voice agent, with pinned dependencies, server-side keys, cleanup, and reproducible offline checks.

Sources reviewed:

What we verified

5 SDK contract and lifecycle fixture checks passed on October 13, 2026. Live connectivity and avatar output remain unverified.

What this example connects

Your LiveKit AgentSession supplies speech recognition, reasoning, and speech synthesis. LemonSlice receives the agent audio and publishes synchronized avatar video in the same room. Keep the voice components you already use.

The downloadable adapter fits inside an existing Python AgentServer job. A working voice agent, an accessible LiveKit server, an active LemonSlice subscription, and a public HTTPS avatar image are the live prerequisites. The example leaves the LemonSlice model unset to use its normal model.

Install the checked versions

First save the adapter, matching requirements file, offline test, and environment template from Example files into one folder. Run these commands from that folder on your backend. The local checks used Python 3.12.14, livekit-agents 1.8.6, and livekit-plugins-lemonslice 1.8.6 on macOS ARM64.

python3.12 -m venv .venv
.venv/bin/python -m pip install -r requirements-livekit.txt

Set up the backend

  • Download livekit_lemonslice.py beside your existing agent entry point.
  • Set LEMONSLICE_API_KEY, LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET, and AVATAR_IMAGE_URL in your server environment. The server-env.example.txt template contains placeholders. Load your own environment before constructing AvatarConfig.
  • Keep provider keys and the LiveKit signing secret on the server. Give the browser a short-lived token restricted to its room.
  • Use one public HTTPS image with an identifiable face and mouth. The helper explicitly disables automatic image editing and keeps a 60-second avatar idle timeout.

Attach video inside your agent job

Call this after constructing your existing session and agent. The helper connects the room, registers cleanup, starts the avatar, and then starts your voice agent. It applies a 30-second startup deadline.

from livekit_lemonslice import AvatarConfig, start_avatar

# Inside your existing AgentServer job:
# ctx is JobContext; session and agent are already configured.
avatar = await start_avatar(
    ctx, session, agent, AvatarConfig.from_environment()
)

# Continue your existing conversation logic here.
# The registered shutdown callback closes the avatar.

Display the avatar and end the session

  • Subscribe your frontend to the avatar participant video and audio tracks. Use a visible connecting state while the first video track is pending.
  • Confirm a subscribed video track or LemonSlice bot_ready event before showing the avatar as ready. A returned provider session ID does not establish that the browser has rendered video.
  • Use your normal agent shutdown path when the user leaves. The adapter registers AvatarSession.aclose with JobContext. Startup rejection or timeout also closes the avatar and disconnects the backend room.
  • During a later live smoke check, confirm one spoken turn, interruption behavior, lip sync, reconnect handling, and that provider usage stops after leaving.

Recover from common failures

  • Authentication failure: verify the server key and active LemonSlice subscription, and confirm the LiveKit URL, API key, and signing secret belong to the same deployment.
  • Avatar image failure: check that the URL returns an image content type and is reachable by the provider without a login.
  • Startup timeout: keep the loading state bounded, close the failed attempt, and retry only after confirming that the previous provider session ended.
  • Audio with no video: check the avatar track subscription and the browser playback state. Keep the readiness signal distinct from the API session response.
  • Stuttering or delayed speech: check TTS streaming and end-of-response handling in your voice pipeline. Keep a finite idle timeout while troubleshooting.

Reproduce the offline check

Five checks passed against the installed SDK: imports and public method signatures, real AvatarSession construction, successful startup ordering, rejected-start cleanup, timeout cleanup, and configuration/key redaction. Success/failure paths use lifecycle fixtures.

Python socket connections are blocked during these checks. Provider HTTP calls, live room joins, browser media, microphones, generated speech, and lip sync were not tested. Run a separate authorized live smoke check with your account before production use.

# From the downloaded example directory:
.venv/bin/python -m unittest test_livekit_offline.py -v

Example files

Official sources

Plan the cost

Read LemonSlice pricing and model notes · Estimate avatar usage · Explore public demos