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

# HeyGen

> AI avatar video generation service for creating interactive conversational avatars

## Overview

`HeyGenVideoService` integrates with HeyGen [LiveAvatar](https://www.liveavatar.com/) to create interactive AI-powered video avatars that respond naturally in real-time conversations. The service handles bidirectional audio/video streaming, avatar animations, voice activity detection, and conversation interruptions to deliver engaging conversational AI experiences with lifelike visual presence.

<CardGroup cols={2}>
  <Card title="HeyGen Video API Reference" icon="code" href="https://reference-server.pipecat.ai/en/latest/api/pipecat.services.heygen.video.html">
    Pipecat's API methods for HeyGen video integration
  </Card>

  <Card title="Example Implementation" icon="play" href="https://github.com/pipecat-ai/pipecat/blob/main/examples/video-avatar/video-avatar-heygen-video-service.py">
    Complete example with interactive avatar
  </Card>

  <Card title="HeyGen Documentation" icon="book" href="https://docs.liveavatar.com/docs/getting-started">
    Official HeyGen API documentation and guides
  </Card>

  <Card title="HeyGen Platform" icon="microphone" href="https://www.liveavatar.com/">
    Access interactive avatars and API keys
  </Card>
</CardGroup>

## Installation

To use HeyGen services, install the required dependency:

```bash theme={null}
uv add "pipecat-ai[heygen]"
```

## Prerequisites

### HeyGen Account Setup

Before using HeyGen video services, you need:

1. **HeyGen Account**: Sign up at [HeyGen Platform](https://app.liveavatar.com/signin)
2. **API Key**: Generate an API key from your account dashboard
3. **Avatar Selection**: Choose from available interactive avatars
4. **Streaming Setup**: Configure real-time avatar streaming capabilities

### Required Environment Variables

* `HEYGEN_LIVE_AVATAR_API_KEY`: Your HeyGen LiveAvatar API key for authentication

## Configuration

<ParamField path="api_key" type="str" required>
  HeyGen API key for authentication.
</ParamField>

<ParamField path="session" type="aiohttp.ClientSession" required>
  HTTP client session for API requests.
</ParamField>

<ParamField path="session_request" type="LiveAvatarNewSessionRequest | NewSessionRequest" default="None">
  Configuration for the HeyGen session. When `None`, defaults to using the
  `"Shawn_Therapist_public"` avatar.
</ParamField>

<ParamField path="service_type" type="ServiceType" default="None">
  Service type for the avatar session.
</ParamField>

<ParamField path="settings" type="HeyGenVideoService.Settings" default="None">
  Runtime-configurable settings. HeyGen has no model-level settings, so this is
  primarily used for the `extra` dict. See [Service
  Settings](/pipecat/fundamentals/service-settings) for details.
</ParamField>

## Usage

### Basic Setup

```python theme={null}
import aiohttp
from pipecat.services.heygen import HeyGenVideoService

async with aiohttp.ClientSession() as session:
    heygen = HeyGenVideoService(
        api_key=os.getenv("HEYGEN_LIVE_AVATAR_API_KEY"),
        session=session,
    )
```

### With Custom Session Request

```python theme={null}
from pipecat.services.heygen.api_liveavatar import LiveAvatarNewSessionRequest

heygen = HeyGenVideoService(
    api_key=os.getenv("HEYGEN_LIVE_AVATAR_API_KEY"),
    session=session,
    session_request=LiveAvatarNewSessionRequest(
        avatar_id="your_avatar_id",
        version="v2",
    ),
)
```

## Notes

* **Bidirectional streaming**: The service manages both sending audio to HeyGen and receiving avatar video/audio back through WebRTC.
* **Interruption handling**: When a user starts speaking, the service interrupts the avatar's current speech, cancels ongoing audio tasks, and activates the avatar's listening animation.
* **Metrics support**: The service supports TTFB metrics tracking using `TTSStartedFrame` and `BotStartedSpeakingFrame` signals.