HeyGen Avatar Plugin for Vision Agents

Deprecated. This plugin is deprecated and will be removed in a future release. Use the Vision Agents LiveAvatar plugin instead — it targets LiveAvatar (by HeyGen) via the supported LITE-mode integration path.

Add realistic avatar video to your AI agents using HeyGen's streaming avatar API.

Features

🎭 Realistic Avatars: Use HeyGen's high-quality avatars with natural movements
🎤 Automatic Lip-Sync: Avatar automatically syncs with audio from any TTS provider
🚀 WebRTC Streaming: Low-latency real-time video streaming via WebRTC
🔌 Easy Integration: Works seamlessly with Vision Agents framework
🎨 Customizable: Configure avatar, quality, resolution, and more

Installation

uv add "vision-agents[heygen]"
# or directly
uv add vision-agents-plugins-heygen

Quick Start

import asyncio
from uuid import uuid4
from dotenv import load_dotenv

from vision_agents.core import User, Agent
from vision_agents.plugins import cartesia, deepgram, getstream, gemini, heygen
from vision_agents.plugins.heygen import VideoQuality

load_dotenv()


async def start_avatar_agent():
    agent = Agent(
        edge=getstream.Edge(),
        agent_user=User(name="AI Assistant with Avatar", id="agent"),
        instructions="You're a friendly AI assistant.",

        llm=gemini.LLM(),
        tts=cartesia.TTS(),
        stt=deepgram.STT(),

        # Add HeyGen avatar
        processors=[
            heygen.AvatarPublisher(
                avatar_id="default",
                quality=VideoQuality.HIGH
            )
        ]
    )

    call = agent.edge.client.video.call("default", str(uuid4()))

    async with agent.join(call):
        await agent.simple_response("Hello! I'm your AI assistant with an avatar.")
        await agent.finish()


if __name__ == "__main__":
    asyncio.run(start_avatar_agent())

Configuration

Environment Variables

Set your HeyGen API key:

HEYGEN_API_KEY=your_heygen_api_key_here

AvatarPublisher Options

from vision_agents.plugins.heygen import VideoQuality

heygen.AvatarPublisher(
    avatar_id="default",  # HeyGen avatar ID
    quality=VideoQuality.HIGH,  # Video quality: VideoQuality.LOW, VideoQuality.MEDIUM, or VideoQuality.HIGH
    resolution=(1920, 1080),  # Output resolution (width, height)
    api_key=None,  # Optional: override env var
)

Usage Examples

With Realtime LLM

from vision_agents.plugins import gemini, heygen, getstream

agent = Agent(
    edge=getstream.Edge(),
    agent_user=User(name="Realtime Avatar AI"),
    instructions="Be conversational and responsive.",

    llm=gemini.Realtime(fps=2),  # No separate TTS needed

    processors=[
        heygen.AvatarPublisher(avatar_id="professional_presenter")
    ]
)

call = agent.edge.client.video.call("default", str(uuid4()))

async with agent.join(call):
    await agent.finish()

With Multiple Processors

from vision_agents.plugins import ultralytics, heygen

agent = Agent(
    edge=getstream.Edge(),
    agent_user=User(name="Fitness Coach"),
    instructions="Analyze user poses and provide feedback.",

    llm=gemini.Realtime(fps=3),

    processors=[
        # Process incoming user video
        ultralytics.YOLOPoseProcessor(model_path="yolo11n-pose.pt"),
        # Publish avatar video
        heygen.AvatarPublisher(avatar_id="fitness_trainer")
    ]
)

How It Works

Connection: Establishes WebRTC connection to HeyGen's streaming API
Audio Input: Receives audio from your TTS provider or Realtime LLM
Avatar Generation: HeyGen generates avatar video with lip-sync
Video Streaming: Streams avatar video to call participants via GetStream Edge

Requirements

Python 3.10+
HeyGen API key (get one at heygen.com)
GetStream account for video calls
TTS provider (Cartesia, ElevenLabs, etc.) or Realtime LLM

Troubleshooting

Connection Issues

If you experience connection problems:

Check your HeyGen API key is valid
Ensure you have network access to HeyGen's servers
Check firewall settings for WebRTC traffic

Video Quality

To optimize video quality:

Use quality=VideoQuality.HIGH for best results
Increase resolution if bandwidth allows
Ensure stable internet connection

API Reference

AvatarPublisher

Main class for publishing HeyGen avatar video.

Methods:

publish_video_track(): Returns video track for streaming
state(): Returns current state information
close(): Clean up resources

License

MIT

Metadata

Release files for vision-agents-plugins-heygen 0.6.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vision-agents-plugins-heygen 0.6.1
File	Size	Uploaded
vision_agents_plugins_heygen-0.6.1.tar.gz	12.5 kB	May 20, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for vision-agents-plugins-heygen 0.6.1
File	Interpreter	ABI	Platform	Reset
vision_agents_plugins_heygen-0.6.1-py3-none-any.whl 33.2 kB May 20, 2026	Python 3	none	any	Details

Total release size: 45.7 kB

Release files / vision_agents_plugins_heygen-0.6.1.tar.gz

Download URL	vision_agents_plugins_heygen-0.6.1.tar.gz
Size	12.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`10075b97f7e6c1d5cab29047ae3d40bc33858d256ce16be948b457a67117f772`
BLAKE2b-256 checksum How to use checksums	`f1f4fec8d53c70d3a1c2c1eca3880236ea8bdba469caeadeab087dffb4046930`
Upload date	May 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.10.6 {"installer":{"name":"uv","version":"0.10.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`

Release files / vision_agents_plugins_heygen-0.6.1-py3-none-any.whl

Download URL	vision_agents_plugins_heygen-0.6.1-py3-none-any.whl
Size	33.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`25fa88fbe4a3d6859c1bbcfa2edb9f569b72586c40dc915ffb699fa0c8be2600`
BLAKE2b-256 checksum How to use checksums	`c2ee046eb7f241c6370fd148202e489dc6fac11b925745fe59685bb9fa2388a3`
Upload date	May 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.10.6 {"installer":{"name":"uv","version":"0.10.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`