PK MiniMax H3 Combined Reference to Video

If you've run MiniMax H3 in ComfyUI, you've hit the fork in the road. The native nodes split the job: one takes your first/last frames, the other takes reference images, video and audio. Pick one, encode, sample. Except nothing in the model asked for that split - ComfyUI's own MiniMaxH3.extra_conds sets minimax_keyframes and minimax_refs independently and feeds both into the same packed layout.

PK MiniMax H3 Combined Reference to Video stuffs all of it into one prompt encode: keyframes, up to nine native reference images, one reference video, one standalone audio clip, and optionally a Media Loader bundle and a RefMod bundle. If you've been chaining two H3 encodes, this removes the compromise.

How it works

It's not a reimplementation - it imports ComfyUI's own comfy_extras.nodes_minimax_h3 helpers for the empty AV latent, canvas adaptation, resizing and reference audio encoding. Keyframes go into the conditioning metadata as minimax_keyframes, VAE-encoded reference blocks as minimax_refs, both set in one clip.encode_from_tokens_scheduled() pass.

The interesting design choice is that every reference has two resolutions: the size it's VAE-encoded at for the DiT (what actually conditions the pixels), and the size it's shown to the Qwen3-VL text encoder at. That decoupling is what vlm_resolution and vlm_video_resolution control, lifted with attribution from silveroxides' UtilsCollection. Practically: hand Qwen a 384px thumbnail, keep the DiT reference sharp, and vision-token cost stops scaling with reference fidelity.

The inputs that actually matter

• clip, prompt, width, height, length - the core. Defaults are 1344×768 and length 124 (~5 seconds at 24fps); the trained range is roughly 124–362.
• vae - optional until you connect first_frame or last_frame, at which point it's mandatory (you'll get a clear error). Without it, reference images and video condition the text encoder only. audio_vae plays the same role for audio.
• ref_image_size - match (the default, and the sane one) scales each reference down to your generation's pixel area. max uses the reference pipeline's 2048px short edge for best identity fidelity, and it is slow: reference tokens ride through every sampling step. none skips the DiT block entirely.
• first_frame, last_frame, reference_images, video, audio - the direct inputs. reference_images is an auto-expanding slot list (0–9), same UI as the native node.
• references / mods - bundle inputs (Media Loader bundle, RefMod bundle) from the wider H3 pack ecosystem. Both optional.

Outputs are conditioning, latent, and reference_map. The latent is the empty AV latent for your width/height/length, so no separate empty-latent node - wire it straight to your sampler. reference_map is the underrated one: a plain string listing every reference in prompt order, like <Picture 1> = first frame or <Video 1> = video. H3 prompts address references by those labels, so pipe it into a Show Text node.

Install

Same as the rest of the pack - ComfyUI Manager, search the pack title, or:

cd ComfyUI/custom_nodes
git clone https://github.com/PlagueKind/ComfyUI-PlagueKind-Nodes.git

Restart ComfyUI. No pip dependencies beyond a standard install, and the pack's most recent commit was literally "remove unintended dependency" - don't let a stray requirements.txt worry you. Bring your own H3 weights, turbo LoRA and VAEs; this node downloads nothing.

One version note: the node registers through ComfyUI's newer V3 authoring API and uses io.Autogrow for the reference slots, so you need a reasonably current ComfyUI and frontend. It loads the native H3 helpers lazily, so an old build starts fine and only fails on run, with "This ComfyUI has no native MiniMax H3 support - update ComfyUI."

And H3 is territory-licensed: in the US, EU, UK or South Korea the community licence doesn't grant you local-use rights. No node pack changes that.

Where people get burned

"Everything's slow and my VRAM vanished." You're on ref_image_size: max with several references. Reference tokens attend at every step; drop to match, or keep match and pull vlm_resolution down to 256–384.

"My reference had no effect." Either ref_image_size is none or vae isn't connected - both paths send references to the text encoder only.

"RefMod errors." The mods input validates hard, because that link type is shared across packs: an incompatible bundle gets a plain-English "has no 'ref_block'" error rather than a stack trace, and strengths must be 0–1. Both bundle inputs expect data this pack doesn't ship. It does ship its own RefMod Loader Stack, which returns an empty bundle and warns in the console if ComfyUI-MiniMaxH3Mod isn't installed.

"My reference video is wrong." It's snapped down to five-frame-plus-17k lengths and truncated past your length.

One caveat: this is a one-person indie pack (updates posted as u/Plague_Kind on r/StableDiffusion) and the README doesn't document this node at all - the source docstring does. When something behaves oddly, read the code; it's short and unusually well commented.