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

# HeyGen Avatars

[HeyGen](https://heygen.com) provides realistic AI avatars with automatic lip-sync. Add a video avatar to your agent that speaks with natural movements synchronized to your agent's voice.

<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[heygen]"
```

## Quick Start

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

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"),
    stt=deepgram.STT(),
    processors=[
        heygen.AvatarPublisher(
            avatar_id="default",
            quality=heygen.VideoQuality.HIGH,
        )
    ],
)
```

<Warning>
  Set `HEYGEN_API_KEY` in your environment or pass `api_key` directly.
</Warning>

## Parameters

| Name         | Type              | Default        | Description                                    |
| ------------ | ----------------- | -------------- | ---------------------------------------------- |
| `avatar_id`  | `str`             | `"default"`    | HeyGen avatar ID (from dashboard)              |
| `quality`    | `VideoQuality`    | `HIGH`         | Quality (`LOW`, `MEDIUM`, `HIGH`)              |
| `resolution` | `Tuple[int, int]` | `(1920, 1080)` | Output resolution                              |
| `api_key`    | `str`             | `None`         | API key (defaults to `HEYGEN_API_KEY` env var) |

## How It Works

The avatar works differently depending on your LLM type:

**With Streaming LLMs (Lower Latency)**

1. LLM generates text → Text sent to HeyGen for lip-sync → HeyGen generates avatar video + audio

**With Realtime LLMs**

1. Realtime LLM generates audio → Audio transcribed → Text sent to HeyGen for lip-sync → HeyGen generates video only (audio from LLM)

```python theme={null}
# With Gemini Realtime
agent = Agent(
    llm=gemini.Realtime(),
    processors=[heygen.AvatarPublisher(avatar_id="default")],
)
```

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