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

> [!NOTE]
>
> Vision Agents uses [Stream Video](https://getstream.io/video/) for real-time WebRTC transport by default. [External WebRTC transports](https://visionagents.ai/integrations/introduction-to-integrations.md#edge-transport) are supported as well. Most AI providers offer free tiers to get started.

> [!NOTE]
>
> Get a LiveAvatar API key and avatar ID from the [LiveAvatar dashboard](https://docs.liveavatar.com).

## 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()`.

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

## Next Steps

> [card] [Build a Voice Agent](https://visionagents.ai/introduction/voice-agents.md)
>
> Get started with voice

> [card] [Build a Video Agent](https://visionagents.ai/introduction/video-agents.md)
>
> Add video processing

> [card] [Build Your Own Avatar](https://visionagents.ai/core/avatar-core.md)
>
> Subclass the `Avatar` base class


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.