Paul de LavallazandClaude Opus 4.6
e138b92ea4
The old endpoints (v2/video/av4/generate and v2/video/generate)
don't support aspect_ratio properly. The new /v2/videos endpoint
natively supports aspect_ratio ("9:16", "16:9") and resolution
("1080p", "720p") without any cropping or post-processing.
Removed all ffmpeg crop code, v2/video/generate, AV4 fallback,
and talking_photo workarounds. Clean simple flow:
upload image + audio → POST /v2/videos → poll → download.
Tested: confirmed 1080x1920 output with full image composition.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
ComfyUI HeyGen Avatar IV (AV4)
ComfyUI custom node for generating realistic talking-head videos using HeyGen's Avatar IV API.
Upload a portrait photo + audio clip and get back a lifelike AI video with natural lip-sync, micro-expressions, and gestures.
Features
- Image + Audio in, Video out -- Connect
Load Image+Load Audio, get a lip-synced video - Avatar IV motion prompts -- Guide gestures and expressions with natural language
- Automatic polling -- The node waits for the video to render and returns it ready for
Save Video - Fallback endpoint -- If the AV4 endpoint fails, automatically falls back to HeyGen's v2 Studio API
Installation
Option 1: Clone
cd ComfyUI/custom_nodes
git clone https://github.com/PauldeLavallaz/comfyui-heygen-av4.git
pip install -r comfyui-heygen-av4/requirements.txt
Option 2: Manual
Download this repository and place the comfyui-heygen-av4 folder inside ComfyUI/custom_nodes/. Restart ComfyUI.
Requirements
- Python 3.10+
requests(auto-installed with ComfyUI)- A HeyGen API key
- ffmpeg recommended (for best audio conversion quality)
Node: HeyGen Avatar IV (AV4)
Category: HeyGen
Inputs
| Input | Type | Required | Description |
|---|---|---|---|
api_key |
STRING | Yes | Your HeyGen API key |
image |
IMAGE | Yes | Portrait photo (from Load Image) |
audio |
AUDIO | Yes | Audio clip (from Load Audio) |
video_title |
STRING | Yes | Title for the generated video |
custom_motion_prompt |
STRING | No | Motion instructions for avatar gestures and expressions |
enhance_custom_motion_prompt |
BOOLEAN | No | Let HeyGen AI enhance the motion prompt (default: true) |
width |
INT | No | Output video width (default: 1920) |
height |
INT | No | Output video height (default: 1080) |
background_type |
COMBO | No | transparent or color (default: transparent) |
background_color |
STRING | No | Hex color when background is color type (default: #FFFFFF) |
poll_interval |
INT | No | Seconds between status checks (default: 5) |
max_poll_checks |
INT | No | Max polls before timeout (default: 120 = 10 min) |
endpoint_mode |
COMBO | No | av4_with_fallback / av4_only / v2_only |
Outputs
| Output | Type | Description |
|---|---|---|
video |
VIDEO | Generated video (connect to Save Video) |
video_id |
STRING | HeyGen video ID for reference |
video_url |
STRING | Direct URL to the generated video (expires in 7 days) |
Usage
Load Image --> [image]
Load Audio --> [audio] --> HeyGen Avatar IV (AV4) --> [video] --> Save Video
api_key: "your-key"
How It Works
- Uploads your image to HeyGen's asset API (returns
image_key) - Uploads your audio to HeyGen's asset API (returns
audio_asset_id) - Calls the Avatar IV generation endpoint with your parameters
- Polls the status endpoint until the video is ready
- Downloads the video and returns it as a ComfyUI VIDEO type
License
MIT