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

# LiveAvatar

[LiveAvatar](https://docs.liveavatar.com) (by [HeyGen](https://heygen.com)) provides real-time interactive avatars with lip-sync driven by your agent's audio. Pass `liveavatar.Avatar()` to the agent's `avatar` parameter to stream synchronized video and audio into the call.

<Info>
  Vision Agents requires a [Stream](https://getstream.io/try-for-free/) account
  for real-time transport. Get a LiveAvatar API key and avatar ID from the
  [LiveAvatar dashboard](https://docs.liveavatar.com).
</Info>

## Installation

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

## Quick Start

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

agent = Agent(
    edge=getstream.Edge(),
    agent_user=User(name="Assistant", id="agent"),
    instructions="You're a friendly AI assistant.",
    llm=gemini.LLM("gemini-3-flash-preview"),
    tts=deepgram.TTS(),
    stt=deepgram.STT(),
    avatar=liveavatar.Avatar(),
)
```

<Warning>
  Set `LIVEAVATAR_API_KEY` and `LIVEAVATAR_AVATAR_ID` in your environment, or
  pass `api_key` and `avatar_id` directly to `Avatar()`.
</Warning>

## Parameters

| Name                   | Type    | Default  | Description                                                         |
| ---------------------- | ------- | -------- | ------------------------------------------------------------------- |
| `avatar_id`            | `str`   | `None`   | LiveAvatar avatar UUID (defaults to `LIVEAVATAR_AVATAR_ID` env var) |
| `api_key`              | `str`   | `None`   | API key (defaults to `LIVEAVATAR_API_KEY` env var)                  |
| `base_url`             | `str`   | `None`   | Override the LiveAvatar API base URL                                |
| `is_sandbox`           | `bool`  | `True`   | Sandbox sessions don't burn credits but are duration-capped         |
| `max_session_duration` | `int`   | `None`   | Session length cap in seconds; `None` uses the API default          |
| `video_quality`        | `str`   | `"high"` | `"low"`, `"medium"`, `"high"`, or `"very_high"`                     |
| `video_encoding`       | `str`   | `"H264"` | `"H264"` or `"VP8"`                                                 |
| `width`                | `int`   | `1280`   | Output video width in pixels                                        |
| `height`               | `int`   | `720`    | Output video height in pixels                                       |
| `fps`                  | `int`   | `30`     | Output video frame rate                                             |
| `buffer_seconds`       | `float` | `1.0`    | Max video buffer depth in seconds ahead of audio playback           |

## How It Works

LiveAvatar runs in [LITE mode](https://docs.liveavatar.com/docs/lite-mode/integration-paths) with the custom-agent integration path:

1. Your agent's TTS (or Realtime LLM) audio is streamed to LiveAvatar over WebSocket
2. LiveAvatar generates lip-synced avatar video and audio
3. Synchronized A/V is published to call participants via Stream Edge

**With standard LLMs**

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

**With Realtime LLMs**

1. Realtime LLM generates audio → Audio sent to LiveAvatar → LiveAvatar returns synchronized avatar video and audio

```python theme={null}
# With Gemini Realtime
agent = Agent(
    llm=gemini.Realtime(),
    avatar=liveavatar.Avatar(is_sandbox=False),
)
```

<Tip>
  Set `is_sandbox=False` in production. Sandbox sessions are free but
  duration-capped.
</Tip>

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