Wild H3 Reference to Video (Ref2VA)

The 2026 answer to character consistency isn't a bolted-on adapter any more - it's handing the model your reference and letting it read it in context. That's why IP-Adapter stalled on SDXL while edit models ate the ecosystem. Ref2VA is that shift applied to video: instead of extracting embeddings and injecting them into cross-attention somewhere, you feed up to nine images and one audio clip to MiniMax H3 and cite them in the prompt text as <Picture 1>, <Picture 2>, <Audio 1>.

This node is the local, Apple Silicon way to do that - the same thin bridge as the pack's Text to Video node, but pointed at h3.c's Ref2VA checkpoint.

What it's for

Keeping something the same across a clip: a product, a character's face, a room. And the audio half is the genuinely new part - a 2-to-15 second audio reference gets cited like an image, so you can hand H3 a voice or a music bed and ask for a clip that matches it, in one generation, with the audio written jointly with the picture rather than dubbed over a silent render. You've stitched a lip-sync pass onto a silent video before; this is that job with the seam taken out.

The community's launch-week read was that H3 does motion transfer "like Kling" - that was said about the model, not this node, so treat it as an invitation to experiment.

How it works

Same subprocess design as the pack's other node: build an h3 command line, run it, stream its stderr progress into ComfyUI's progress bar, return the mp4 as a VIDEO. What differs is what's passed. Each reference image in the batch gets written out as a PNG in the temp dir and appended as its own --ref-image <path>, in order; audio becomes a 16-bit PCM WAV behind --ref-audio.

The prompt is where references get bound. The node hands h3 your images; only your text says which is the character and which is the room. Write the citations in.

Inputs that matter

ref_images takes an IMAGE batch. Order is citation order - the first image in the batch is <Picture 1>, so how you build the batch is how you number the references. One real behaviour in the current source: images past the ninth are silently dropped rather than erroring, so a batch of twelve quietly becomes nine.

ref_audio takes one AUDIO and requires at least one reference image; without one, preflight fails outright. It must be 2 to 15 seconds, and the check measures the actual waveform, not the filename you hoped was right.

ref_image_size is advanced, with two options, match (default) and max. It passes straight through to h3's own --ref-image-size, and the author's tooltip is one line, so leave it alone unless you've got a specific reason.

Everything else is shared with the Text to Video node: prompt, width/height (multiples of 32, area capped at 768×1344), seconds (0.25–15, snapped to h3's frame chunks), steps, preset (precise/balanced/fast - 50/45/40 layers at reuse 1/2/3), the 64-bit seed, and the advanced token_reduction, ssd_streaming, binary_path and model_dir.

Notice what's absent: no first_frame or last_frame. Anchoring and reference conditioning don't mix, and the pack enforces that by splitting them across two nodes rather than trusting you to remember - so pick one per generation.

Output is a single video, straight into Save Video.

Install

ComfyUI Manager, search Wild H3C, or:

cd ComfyUI/custom_nodes
git clone https://github.com/skaiy/wild-h3c-comfyui.git

Then the setup the manager won't do: macOS on Apple Silicon, ffmpeg/ffprobe on PATH, a ComfyUI new enough for the V3 schema (the pack registers via comfy_entrypoint()), and the engine built from source:

git clone https://github.com/antirez/h3.c.git && cd h3.c && make -j8

Here's the part that catches people: this node needs the Ref2VA checkpoint, not just FL2VA. If you took the cheap path and grabbed FL2VA only - about 134 GB - Text to Video works fine and this node won't. The full set is roughly 268 GB, laid out as MiniMax-H3/FL2VA/ and MiniMax-H3/Ref2VA/.

{ "h3_binary": "~/h3.c/h3", "model_dir": "~/h3.c/MiniMax-H3" }

model_dir is the folder containing FL2VA/, not FL2VA itself. Confirm the download with ./h3 --info -d <path>/MiniMax-H3 before you debug anything else.

Where people get burned

Editing config.json and seeing no change. It's read once and cached per process - restart ComfyUI. The node description reads binary: (not configured) if your paths never took.

Silence on the first run while the checkpoint loads: tens of seconds with no progress lines, then the bar appears. Wait it out.

Feed references, get nothing. Cite them. An uncited image is just a file h3 was handed.

Preflight failures are exact, so read them. Empty prompt, non-multiple-of-32 dimensions, area over 768×1344, audio under 2 seconds, audio with no images - each gets its own message naming the rule.

One at a time. h3 calls are serialized behind a global lock; variations queue up rather than run in parallel.

The licence isn't the plugin's. Code is MIT; the weights fall under the MiniMax H3 Community License, which excludes the US, EU, UK and South Korea from its Applicable Territory - outputs included - and gates commercial use on revenue. Check that before committing the disk space.