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.HIGHfor 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 streamingstate(): Returns current state informationclose(): Clean up resources
License
MIT
Links
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)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| vision_agents_plugins_heygen-0.6.1.tar.gz | 12.5 kB | Without provenance | Details for vision_agents_plugins_heygen-0.6.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| vision_agents_plugins_heygen-0.6.1-py3-none-any.whl | Python 3 | none | any | Details for vision_agents_plugins_heygen-0.6.1-py3-none-any.whl |
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 | |
|
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 | |
|
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}
|
Security for vision-agents-plugins-heygen 0.6.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.