LemonSlice virtual avatar integration guide

Overview

LemonSlice provides lifelike realtime avatars that naturally interact with users. You can use the open source LemonSlice integration for LiveKit Agents to seamlessly add virtual avatars to your voice AI app.

Quick reference

This section includes a basic usage example and some reference material. For links to more detailed documentation, see Additional resources.

Installation

Install the plugin from PyPI:

uv add "livekit-plugins-lemonslice~=1.3"

Authentication

The LemonSlice plugin requires a LemonSlice API key.

Set LEMONSLICE_API_KEY in your .env file.

Avatar setup

The LemonSlice plugin requires either a base image set by agent_image_url or an agent ID set by agent_id to start an avatar session. Only one of these parameters can be configured.

Agent Image URL

The LemonSlice plugin accepts a source image URL from which to generate the avatar. The avatars render as 368x560 pixel videos. LemonSlice will automatically center-crop your image to the target aspect ratio if the dimensions do not match the expected values. LemonSlice supports a wide range of faces, from humanoid to animal, and styles from photorealistic to animated. Best results are achieved with anthropomorphic images where the face and mouth are clearly identifiable. The image URL must be publicly accessible and return an image/* content type.

Agent ID

To use an existing LemonSlice agent as your avatar, set the agent_id in AvatarSession. You can find the agent ID in the LemonSlice agent dashboard. You can also create new LemonSlice agents through the agent creation flow by specifying an image.

Usage

Use the plugin in an AgentSession. For example, you can use this avatar in the Voice AI quickstart.

from livekit import agents
from livekit.agents import AgentServer, AgentSession
from livekit.plugins import lemonslice

server = AgentServer() 

@server.rtc_session()
async def my_agent(ctx: agents.JobContext):
    session = AgentSession(
        # ... stt, llm, tts, etc.
    ) 
    
    avatar = lemonslice.AvatarSession(
        # Publicly accessible image URL for the avatar
        agent_image_url="...",
        # Prompt to guide the avatar's movements
        agent_prompt="Be expressive in your movements and use your hands while talking."
    )
    
    # Start the avatar and wait for it to join
    await avatar.start(session, room=ctx.room)
    
    # Start your agent session with the user
    await session.start(
        # ... room, agent, room_options, etc....
    )

Preview the avatar in the Agents Playground or a frontend starter app that you build.

Parameters

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

Additional resources

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

Python package

The livekit-plugins-lemonslice package on PyPI.

Plugin reference

Reference for the LemonSlice avatar plugin.

GitHub repo

View the source or contribute to the LiveKit LemonSlice avatar plugin.

LemonSlice docs

LemonSlice's full docs site.

Agents Playground

A virtual workbench to test your avatar agent.

Frontend starter apps

Ready-to-use frontend apps with avatar support.