LemonSlice

View saved version →

---
name: lemonslice-livekit-app
description: |
  Add a LemonSlice video avatar to a LiveKit Agents app, or build one from scratch. LemonSlice turns any single image into a real-time, lip-synced talking avatar that joins the LiveKit room as a participant. Use when: (1) the user wants a talking avatar, a face on a voice agent, a lip-synced character, or a video agent on LiveKit — even if they do not name LemonSlice; (2) they mention lemonslice.AvatarSession, livekit-agents[lemonslice], @livekit/agents-plugin-lemonslice, or the lemonslice-examples repo; (3) they want the avatar to move and emote on its own or on cue (CWM-1, Character World Model, emotion engine, waving, smiling, laughing, leaning in), or to change its image or demeanor mid-call (update-image); (4) they are moving from another LiveKit avatar plugin (Tavus, HeyGen, Hedra, Beyond Presence, Anam, Synthesia); (5) the avatar never shows up, shows a black frame, drops after a fixed number of minutes, or the audio doubles. Works for Python and Node.js agents.
license: MIT
metadata:
  author: lemonslice
  version: "1.0.0"
---

# LemonSlice avatar on LiveKit

LemonSlice is an avatar plugin for LiveKit Agents, in Python and Node.js. You give it one image (any face, any art style, no training step) and it joins the room as a second participant that publishes lip-synced video. Your `AgentSession` keeps doing STT, LLM, and TTS; the plugin reroutes the session's audio to LemonSlice, which streams synced audio and video back into the room.

This skill works out what the user already has, picks one route, and implements it.

## Facts that shape every decision

- **Keys.** `LEMONSLICE_API_KEY` from https://lemonslice.com/developers, plus `LIVEKIT_URL`, `LIVEKIT_API_KEY`, `LIVEKIT_API_SECRET` from a LiveKit Cloud project. The LemonSlice key needs an active subscription; a key without one gets a `401`/`402` from the session API. Nothing runs without these, so confirm them before writing code.
- **Source image.** Exactly one of `agent_image_url` (public `https://` URL), `agent_image` (local file, uploaded by the plugin), or `agent_id` (an avatar saved in the LemonSlice dashboard). Default to `agent_image_url`; the dashboard is optional. Site paths like `/avatar.png` and `localhost` URLs fail because LemonSlice's servers fetch the image.
- **Both languages.** Python: `livekit-agents[lemonslice]`. Node: `@livekit/agents-plugin-lemonslice`. The frontend is just a LiveKit client.
- **Attach before start.** `await avatar.start(session, room)` must finish before `await session.start(...)`.
- **The avatar owns the audio.** Keep `audio_output=False` in `RoomOptions` (Python) or the equivalent in Node, and do not give the session another audio output afterwards. Otherwise the user hears the reply twice, or lip-sync dies.
- **Sessions time out.** Idle timeout defaults to 60 s and resets while the avatar talks (`idle_timeout`, `-1` disables). Hard cap is 30 minutes per session unless LemonSlice raises it.
- **Mid-call control is a REST call, not a plugin method.** Image and demeanor prompts change via `POST /api/liveai/sessions/{session_id}/control`. `avatar.start()` returns the `session_id` you need.
- **CWM-1 is the behavior model.** `model="cwm-1"` (or `"cwm-1-lite"`) switches the avatar to Character World Model 1, whose emotion engine decides what the character does and feels: waving, smiling, laughing, leaning in, glancing away. It can run fully automatically (`action_engine="natural"`) or take cues from your code. Under CWM-1, `agent_prompt` and `agent_idle_prompt` are ignored.
- **Plan-gated.** CWM-1 and `model="flash"` (fastest response) are on the Ultra and Enterprise tiers. Offer them; do not build on them until the user confirms their plan.

## Step 1: Find the starting point

Scan the codebase before asking anything.

| Look for | Where | Means |
| --- | --- | --- |
| `livekit-agents` / `livekit.agents` | `pyproject.toml`, imports | Python LiveKit agent → **Add** |
| `@livekit/agen

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.