Hedra Image to Video

The name is honest about the trick: this node doesn't render anything

The Hedra Image to Video node takes one portrait image and one audio file, hands both to Hedra's Character-3 API, and comes back with a lip-synced talking-avatar video. There's no model downloaded to your machine, no VRAM being chewed, no local inference. It's a thin wrapper around a paid cloud service - the ComfyUI side of the work is just packaging your inputs, uploading them, and turning the result back into tensors ComfyUI can use.

Why would you reach for it when local alternatives like HunyuanVideo-Avatar or LTX-2 lip-sync exist? Honest answer: because Character-3 does something most local pipelines don't nail - coordinated background animation. The curtains flutter, the plants sway, the environment reacts to the speaker's energy instead of sitting frozen behind the head. Hedra's whole selling point is that scene coherence, and it's genuinely hard to get locally. The trade is that you pay per second of video (roughly 3.5–7 credits per second, so a 30-second clip runs 105–210 credits) and you need a Hedra account with a paid plan and an API key. There's also a use_test_mode toggle that returns placeholder outputs without burning any credits, which is exactly how you should test your workflow wiring before spending real money.

How it works under the hood

Looking at the source, the flow is straightforward. The node:

1. Reads your API key from config.json in the node folder.
2. Converts the IMAGE tensor to a PNG and the AUDIO to a temp WAV.
3. Creates assets, uploads both files, then creates a generation against https://api.hedra.com/web-app/public.
4. Polls every 5 seconds (up to 10 minutes) until the job completes, fails, or times out.
5. Downloads the MP4, extracts every frame with OpenCV, and returns them as an IMAGE batch.

That last step is the one that'll bite you. A 30-second clip at 24 FPS is 720 frames. Returned as a single image batch, that's a chunky tensor, and if you wire images straight into a Video Combine node you can hammer your RAM or VRAM for no reason. If you only need the finished file, grab the video_url output and download it once - the node already spent a long time fetching it anyway.

The inputs that actually matter

Required: image (the portrait - clear face, and per Hedra's own advice, distinct background elements help) and audio (any node that outputs the ComfyUI AUDIO type; WAV is the safest bet). That's all you must connect to get something out.

Then the three you'll actually touch:

• aspect_ratio - 16:9, 9:16, or 1:1. Default 16:9. For vertical TikTok/Reels content, 9:16 is your friend.
• resolution - 540p or 720p. 720p is the default and costs more credits; 540p is fine for test runs.
• prompt - the tooltip's the truth here: describe emotions, gestures, and scene dynamics. "speaking enthusiastically with hands, background gently swaying" reads far better than an empty string.

use_test_mode (default false) skips the API entirely and returns a placeholder. debug_mode (default true) prints the whole pipeline to your console - masked key, asset IDs, status poll results - and it's your first stop when a generation fails.

Outputs: images (frame batch), audio (your original audio, passed through untouched), frame_count (how many frames came back), and video_url (the hosted MP4 link).

Installing it

cd ComfyUI/custom_nodes
git clone https://github.com/ShmuelRonen/ComfyUI_Hedra.git
cd ComfyUI_Hedra
pip install -r requirements.txt

Then restart ComfyUI. ComfyUI Manager can also find it if you search the pack title. Good news: requirements.txt is just scipy and opencv-python - no heavy deps, no model downloads, nothing to babysit. The node creates a default config.json on first load; open it and put your real key in.

Where people get burned

The config gotcha is real: the auto-created config.json ships with "put_your_hedra_api_key_here", but the code's own sanity check looks for "your_api_key_here". So the placeholder slips past the friendly "set your key" error and you just get a 401 from Hedra's API. If that's you, open config.json, paste your sk_h... key, and enable debug_mode to confirm it's being read.

Beyond that: audio that isn't a clean WAV will fail, an image without a clear face will produce garbage, and if nothing happens at all, check use_test_mode is off. Hedra is a paid SaaS - the r/StableDiffusion crowd has historically been skeptical of it as self-promotion, and if you're on a GPU with spare VRAM, the free local route (Hallo, LivePortrait, HunyuanVideo-Avatar) may serve you just as well. But if you want that animated background in a couple of minutes and you don't mind paying per second, this is a clean way to bolt it onto a ComfyUI workflow.