JZL - 🎬 MiniMax H3 参考编码

"JZL - 🎬 MiniMax H3 参考编码" is the pack's flagship: a from-scratch reproduction of ComfyUI's official MiniMaxH3ReferenceToVideo ref2va node, and the README is upfront that it's a "100% replica" of the official behavior - with one JZL extension bolted on. H3 itself is the 33B open-weight omni-modal video model with native stereo audio, and ref2va is its reference-conditioning mode: you hand it reference images, reference videos, and reference audio, tag them in the prompt, and it encodes everything into the conditioning + latent that drives generation. This is the node that makes "give the model this character's face, this scene, and this voice" work.

Why replicate an official node at all? Because the pack's pipeline wants one consistent, in-house encoder that both its V1 classic nodes and its V3 io.Schema nodes can share, and because the author wanted room to add the ref_scale extension without patching ComfyUI core. Since H3 got day-zero ComfyUI support and the community reaction was strong, the demand for exactly this kind of node is real.

How it works

It's a proper io.Schema V3 node. The four reference groups use io.Autogrow - connect a reference and the next empty slot grows automatically, just like the official node:

• ref_images - up to 9 reference images (auto-shrunk to a 2048 short edge, never upscaled)
• ref_videos - up to 3 reference videos, 2–15s at 24fps
• ref_video_audios - the matching soundtracks, index-paired with their videos
• ref_audios - up to 3 standalone reference audios

In the prompt you reference them by tag: <Picture 1>, <Video 2>, <Audio 3> (indexed per type, from 1). The encoder VAE-encodes images and videos (videos downsampled to 2fps with timestamps for the Qwen tokenizer), resamples and encodes audio through the audio_vae, and attaches everything as minimax_refs on the conditioning. Outputs: positive (CONDITIONING) and LATENT (the empty AV latent).

The JZL extension is ref_scale (1.0–5.0, default 1.0 = official behavior). It only applies in match mode and it's an area multiplier, not resolution: final reference pixel area = canvas area × scale. 2.0 doubles the reference image's area for stronger identity fidelity - at the cost of speed, because reference tokens participate in every sampling step. ref_image_size gives you the two strategies: match (scale to canvas area) or max (align short edge to 2048, best identity but potentially several times slower).

The inputs that matter

• prompt - write <Picture i> / <Video k> / <Audio j> tags here.
• clip, vae, audio_vae - the three encoders. All required; no audio_vae, no audio references.
• length - frame count, default 124 (≈5s at 24fps), snapped to the 17k+5 grid.
• ref_image_size / ref_scale - the fidelity/speed trade-off knobs.

How to install it

Pack install - ComfyUI Manager, search "ComfyUI-JZL-MiniMax-H3", or:

cd ComfyUI/custom_nodes
git clone https://github.com/wjluoxiao/ComfyUI-JZL-MiniMax-H3

Restart. It's a V3 node, so you need a recent ComfyUI with comfy_api.latest (the same build that ships the official H3 nodes). Dependencies: torch, torchaudio (audio encode), and you supply the model via ComfyUI's official H3 loaders - the ~42.5GB weights, which the MiniMax H3 Community License excludes from the US, EU, UK, and South Korea.

Common issues

The most common failure is a reference video shorter than 5 frames - the encoder raises a hard error ("need at least 5 frames ~0.2s at 24 fps"). Also, cranking ref_scale to 3–5 "for fidelity" is the classic performance trap; start at 1.0–2.0. And if you're in a geofenced region, remember the API route (Hailuo) is the licensed path - the local weights aren't.