> ## 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

[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(),
    avatar=lemonslice.Avatar(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)                        |
| `base_url`           | `str`   | `None`  | Override the LemonSlice API base URL                                      |
| `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`   | `1280`  | Output video width in pixels                                              |
| `height`             | `int`   | `720`   | Output video height in pixels                                             |
| `fps`                | `int`   | `30`    | Output video frame rate. Must be `> 0`.                                   |
| `buffer_seconds`     | `float` | `1.0`   | Max video buffer depth in seconds ahead of audio playback. Must be `> 0`. |

## 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(),
    avatar=lemonslice.Avatar(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.Avatar(
    agent_image_url="https://example.com/avatar.png",  # 368x560px recommended
    agent_prompt="A friendly customer service representative",
)
```

## Next steps

<CardGroup cols={3}>
  <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>

  <Card title="Build your own avatar" icon="code" href="/core/avatar-core">
    Subclass the `Avatar` base class
  </Card>
</CardGroup>