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

# HeyGenTransport

> AI avatar video generation service for creating interactive conversational avatars

## Overview

`HeyGenTransport` enables your Pipecat bot to join the same virtual room as a HeyGen avatar and human participants. The transport integrates with the HeyGen [LiveAvatar](https://www.liveavatar.com/) platform 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.

When used, the Pipecat bot connects to a LiveKit room alongside the HeyGen avatar and user. The bot receives audio input from participants, processes it through your pipeline, and sends TTS audio to the HeyGen avatar for synchronized video rendering.

<CardGroup cols={2}>
  <Card title="HeyGen Trasnport API Reference" icon="code" href="https://reference-server.pipecat.ai/en/latest/api/pipecat.transports.heygen.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-transport.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

### HeyGenTransport

<ParamField path="session" type="aiohttp.ClientSession" required>
  An aiohttp session for making async HTTP requests to the HeyGen API.
</ParamField>

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

<ParamField path="params" type="HeyGenParams" default="HeyGenParams()">
  Transport configuration parameters.
</ParamField>

<ParamField path="input_name" type="str" default="None">
  Optional name for the input transport processor.
</ParamField>

<ParamField path="output_name" type="str" default="None">
  Optional name for the output transport processor.
</ParamField>

<ParamField path="session_request" type="LiveAvatarNewSessionRequest | NewSessionRequest" default="None">
  Configuration for the HeyGen session, including avatar selection and settings.
</ParamField>

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

### HeyGenParams

Inherits from `TransportParams` with the following defaults changed:

<ParamField path="audio_in_enabled" type="bool" default="True">
  Whether to enable audio input from participants.
</ParamField>

<ParamField path="audio_out_enabled" type="bool" default="True">
  Whether to enable audio output to participants.
</ParamField>

## Usage

HeyGenTransport creates a three-way conversation between your Pipecat bot, a HeyGen avatar, and human participants. The transport manages the HeyGen API session and room connectivity automatically.

See the [complete example](https://github.com/pipecat-ai/pipecat/blob/main/examples/video-avatar/video-avatar-heygen-transport.py) for a full implementation including:

* HeyGen transport configuration with API key and session setup
* Avatar selection and streaming configuration
* Pipeline integration with TTS
* Event handling for participant management

## Event Handlers

HeyGenTransport provides event handlers for participant connection lifecycle. Register handlers using the `@event_handler` decorator on the transport instance.

### Events Summary

| Event                    | Description                                            |
| ------------------------ | ------------------------------------------------------ |
| `on_connected`           | Bot connected to the LiveKit room                      |
| `on_client_connected`    | Participant (non-avatar) connected to the session      |
| `on_client_disconnected` | Participant (non-avatar) disconnected from the session |

<Note>
  The HeyGen avatar participant is automatically filtered out from these events.
  Only human participant connections trigger the event handlers.
</Note>

### Room Lifecycle

#### on\_connected

Fired when the bot connects to the LiveKit room.

```python theme={null}
@transport.event_handler("on_connected")
async def on_connected(transport):
    print("Bot connected to LiveKit room")
```

**Parameters:**

| Parameter   | Type              | Description            |
| ----------- | ----------------- | ---------------------- |
| `transport` | `HeyGenTransport` | The transport instance |

### Connection Lifecycle

#### on\_client\_connected

Fired when a human participant connects to the session. The HeyGen avatar is filtered out from this event.

```python theme={null}
@transport.event_handler("on_client_connected")
async def on_client_connected(transport, participant):
    print(f"Client connected: {participant}")
```

**Parameters:**

| Parameter     | Type              | Description                |
| ------------- | ----------------- | -------------------------- |
| `transport`   | `HeyGenTransport` | The transport instance     |
| `participant` | `str`             | The participant identifier |

#### on\_client\_disconnected

Fired when a human participant disconnects from the session.

```python theme={null}
@transport.event_handler("on_client_disconnected")
async def on_client_disconnected(transport, participant):
    print(f"Client disconnected: {participant}")
```

**Parameters:**

| Parameter     | Type              | Description                |
| ------------- | ----------------- | -------------------------- |
| `transport`   | `HeyGenTransport` | The transport instance     |
| `participant` | `str`             | The participant identifier |

## Additional Resources

* [Events Overview](/api-reference/server/events/overview) - Overview of all events in Pipecat