> ## 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 uses [Stream Video](https://getstream.io/video/) for real-time WebRTC transport by default. [External WebRTC transports](/integrations/introduction-to-integrations#edge-transport) are supported as well. Most AI providers offer free tiers to get started.
</Info>

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


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