HeyGen Avatar IV (AV4)

First, the honest framing: this node does not run anything locally. HeyGenAvatarIV is a thin bridge from your ComfyUI graph to HeyGen's Avatar IV API, a paid cloud service. You hand it a portrait and an audio clip, it returns a lifelike talking-head video with natural lip-sync, micro-expressions, and gestures. The local-generation crowd keeps asking how to replicate HeyGen in ComfyUI. Short answer: you don't - you wire HeyGen into ComfyUI instead, which is exactly what this pack does.

What you're actually building

The point is ComfyUI-as-glue. You keep doing the fun local work in the graph - the portrait generation, the cleanup, the voice clip from your TTS nodes - and then this node takes the IMAGE and AUDIO tensors straight off your wires and hands them to HeyGen. No exporting, no re-uploading files by hand - that's the entire value proposition.

The workflow is about as short as ComfyUI gets:

Load Image ──> [image]
                              HeyGenAvatarIV ──> [video] ──> Save Video
Load Audio ──> [audio]                        ──> [video_id]
                                              ──> [video_url]

How it works

The source is small enough to read in one sitting, which is a good sign. Under the hood it:

1. Converts your IMAGE tensor to PNG bytes and uploads it to HeyGen's asset endpoint (upload.heygen.com/v1/asset), returning an image_asset_id.
2. Converts your AUDIO tensor to MP3/WAV and uploads it the same way. Audio conversion is a clever cascade: ffmpeg MP3 first if it's available, then torchaudio, then a pure-Python WAV fallback. So ffmpeg is recommended for best quality but genuinely optional - the node won't die without it.
3. POSTs to api.heygen.com/v2/videos with the two asset IDs plus resolution, aspect ratio, and optional motion prompt.
4. Polls the status endpoint every 5 seconds, up to 120 times - a hard 10-minute cap.
5. Downloads the finished MP4 into ComfyUI's output folder and returns it as a VIDEO type, ready for Save Video.

Each render bills against your HeyGen account, so don't accidentally fire it in a 50-iteration batch loop. Ask me how I know.

The inputs that matter

Only a handful of knobs exist, and that's the right call:

• api_key (required) - your HeyGen API key from app.heygen.com/settings. The node raises a ValueError if it's blank, which is a nicer failure than a cryptic 401.
• image and audio (required) - wire from Load Image / Load Audio. A clean, centered, well-lit portrait gets dramatically better results than a busy crop.
• aspect_ratio - 9:16 or 16:9, default 9:16. This is the vertical-Short format default; flip it if you're making widescreen.
• resolution (optional) - 1080p or 720p. 720p is cheaper and plenty for test renders.
• motion_prompt (optional, multiline) - natural-language instructions for gestures and expressions, e.g. "nod occasionally, gesture with hands, smile warmly." Leave it empty and HeyGen picks sensible default movement.

One real gotcha: the GitHub README advertises more knobs than the installed node actually has - width, height, background_type, an "endpoint fallback" mode, all of it. The shipped code doesn't contain those. Trust the node's actual inputs, not the README's aspirational list.

Outputs

• video - the VIDEO output; wire it into Save Video.
• video_id - HeyGen's ID, handy if you need to look the render up in their dashboard.
• video_url - a direct download link. It expires (roughly 7 days), so grab the local video output if you need to keep it.

Installing it

Either path works; ComfyUI Manager is easiest - search "comfyui-heygen-av4" and install. Manual route:

cd ComfyUI/custom_nodes
git clone https://github.com/PauldeLavallaz/comfyui-heygen-av4.git
pip install -r comfyui-heygen-av4/requirements.txt

Restart ComfyUI and look under the HeyGen category. The dependency list is almost a joke in the best way: requests is the only real addition, since Pillow, numpy, and torch already ship with ComfyUI.

Troubleshooting

• "Timed out after 600s" - HeyGen is just slow, especially on busy days. The node hard-caps polling at 10 minutes and raises if the video isn't done. Bump nothing; just rerun or render during off-peak.
• No ffmpeg? You're fine - the node silently falls back to torchaudio and then to a stdlib WAV encoder. Install ffmpeg anyway if you care about audio quality.
• VIDEO type issues on old builds - the node uses ComfyUI's newer comfy_api VideoFromFile wrapper to build the VIDEO output. On older ComfyUI versions that import may not exist and it degrades to returning a file path string. If Save Video doesn't accept the wire, update ComfyUI.
• Cost and privacy - every run is a paid cloud render, and your portrait and audio leave your machine. If that's a dealbreaker, local lip-sync options in ComfyUI do exist (HunyuanVideo-Avatar-style workflows), but they won't match HeyGen's production polish without serious setup.

It's a small node with a clear job: get HeyGen-grade talking heads inside your ComfyUI graph without hand-exporting assets. For that, it's the one I'd reach for.