Skip to main content

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

HeyGen Trasnport API Reference

Pipecat’s API methods for HeyGen video integration

Example Implementation

Complete example with interactive avatar

HeyGen Documentation

Official HeyGen API documentation and guides

HeyGen Platform

Access interactive avatars and API keys

​
Installation

To use HeyGen services, install the required dependency: 
pip install "pipecat-ai[heygen]"

​
Prerequisites

​
HeyGen Account Setup

Before using HeyGen video services, you need:
  1. HeyGen Account: Sign up at HeyGen Platform
  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

​
session
aiohttp.ClientSession
required
An aiohttp session for making async HTTP requests to the HeyGen API.
​
api_key
str
required
HeyGen API key for authentication.
​
params
HeyGenParams
default:"HeyGenParams()"
Transport configuration parameters.
​
input_name
str
default:"None"
Optional name for the input transport processor.
​
output_name
str
default:"None"
Optional name for the output transport processor.
​
session_request
LiveAvatarNewSessionRequest | NewSessionRequest
default:"None"
Configuration for the HeyGen session, including avatar selection and settings.
​
service_type
ServiceType
default:"None"
Service type for the avatar session.

​
HeyGenParams

Inherits from TransportParams with the following defaults changed:
​
audio_in_enabled
bool
default:"True"
Whether to enable audio input from participants.
​
audio_out_enabled
bool
default:"True"
Whether to enable audio output to participants.

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

EventDescription
on_client_connectedParticipant (non-avatar) connected to the session
on_client_disconnectedParticipant (non-avatar) disconnected from the session
The HeyGen avatar participant is automatically filtered out from these events. Only human participant connections trigger the event handlers.

​
Connection Lifecycle

​
on_client_connected

Fired when a human participant connects to the session. The HeyGen avatar is filtered out from this event. 
@transport.event_handler("on_client_connected")
async def on_client_connected(transport, participant):
    print(f"Client connected: {participant}")
Parameters:
ParameterTypeDescription
transportHeyGenTransportThe transport instance
participantstrThe participant identifier

​
on_client_disconnected

Fired when a human participant disconnects from the session. 
@transport.event_handler("on_client_disconnected")
async def on_client_disconnected(transport, participant):
    print(f"Client disconnected: {participant}")
Parameters:
ParameterTypeDescription
transportHeyGenTransportThe transport instance
participantstrThe participant identifier

​
Additional Resources