> ## Documentation Index
> Fetch the complete documentation index at: https://visionagents.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# LemonSlice Avatars

[LemonSlice](https://lemonslice.com) provides real-time interactive AI avatars with synchronized lip-sync. Add a self-managed video avatar to your agent that speaks with natural movements and expressions.

<Info>
  Vision Agents requires a [Stream](https://getstream.io/try-for-free/) account
  for real-time transport. Most providers offer free tiers to get started.
</Info>

## Installation

```sh theme={null}
uv add "vision-agents[lemonslice]"
```

## Quick start

```python theme={null}
from vision_agents.core import Agent, User
from vision_agents.plugins import cartesia, deepgram, getstream, gemini, lemonslice

agent = Agent(
    edge=getstream.Edge(),
    agent_user=User(name="Assistant", id="agent"),
    instructions="You're a friendly AI assistant.",
    llm=gemini.LLM(),
    tts=cartesia.TTS(),
    stt=deepgram.STT(),
    processors=[
        lemonslice.LemonSliceAvatarPublisher(
            agent_id="your-avatar-id",
        )
    ],
)
```

<Warning>
  Set the following environment variables:

  * `LEMONSLICE_API_KEY` - Your LemonSlice API key
  * `LIVEKIT_URL` - Your LiveKit server URL (e.g., `wss://your-server.livekit.cloud`)
  * `LIVEKIT_API_KEY` - Your LiveKit API key
  * `LIVEKIT_API_SECRET` - Your LiveKit API secret
</Warning>

## Parameters

| Name                 | Type  | Default | Description                                                    |
| -------------------- | ----- | ------- | -------------------------------------------------------------- |
| `agent_id`           | `str` | `None`  | LemonSlice agent ID (from dashboard)                           |
| `agent_image_url`    | `str` | `None`  | Custom avatar image URL (368x560px) - alternative to agent\_id |
| `agent_prompt`       | `str` | `None`  | Prompt to influence avatar expressions and movements           |
| `idle_timeout`       | `int` | `None`  | Seconds before an idle session is closed                       |
| `api_key`            | `str` | `None`  | API key (defaults to `LEMONSLICE_API_KEY` env var)             |
| `livekit_url`        | `str` | `None`  | LiveKit server URL (defaults to `LIVEKIT_URL` env var)         |
| `livekit_api_key`    | `str` | `None`  | LiveKit API key (defaults to `LIVEKIT_API_KEY` env var)        |
| `livekit_api_secret` | `str` | `None`  | LiveKit API secret (defaults to `LIVEKIT_API_SECRET` env var)  |
| `width`              | `int` | `1920`  | Output video width in pixels                                   |
| `height`             | `int` | `1080`  | Output video height in pixels                                  |

## How it works

The avatar works differently depending on your LLM type:

**With standard LLMs**

1. LLM generates text → TTS converts to audio → Audio sent to LemonSlice → LemonSlice generates synchronized avatar video and audio

**With Realtime LLMs**

1. Realtime LLM generates audio → Audio sent to LemonSlice → LemonSlice generates video only (audio from LLM)

```python theme={null}
# With Gemini Realtime
agent = Agent(
    llm=gemini.Realtime(),
    processors=[lemonslice.LemonSliceAvatarPublisher(agent_id="your-avatar-id")],
)
```

## Custom avatar image

Instead of using a pre-configured agent ID, you can provide a custom avatar image:

```python theme={null}
lemonslice.LemonSliceAvatarPublisher(
    agent_image_url="https://example.com/avatar.png",  # 368x560px recommended
    agent_prompt="A friendly customer service representative",
)
```

## Next steps

<CardGroup cols={2}>
  <Card title="Build a voice agent" icon="microphone" href="/introduction/voice-agents">
    Get started with voice
  </Card>

  <Card title="Build a video agent" icon="video" href="/introduction/video-agents">
    Add video processing
  </Card>
</CardGroup>