MiniMax H3 Ref Load

The simplest node in the MiniMax H3 reference family, and the one that pays for the whole setup: UC_MiniMaxH3RefLoad reads a reference artifact off disk and hands it back as a MINIMAX_H3_REF, ready for MiniMax H3 Ref Apply.

That's it. One input, filename, chosen from a dropdown rather than by typing a path - the list comes from ComfyUI/models/minimax_h3_refs plus any additional reference folders you've configured, and it only shows .safetensors files.

Why bother, when MiniMax H3 Ref Extract exists and works fine inline? Because extraction is a VAE pass and loading is a file read. If your reference is a set of eight storyboard frames, or a video clip, or a voice sample you'll use across a dozen generations, you want to encode it once and then treat it like a model - pick it from a dropdown, swap it, reuse it. That's the actual workflow improvement here, and it's the same reason LoRAs are files and not prompts.

What it accepts

The loader is built to read the reference format generally, not just files this pack wrote. It looks for the metadata header under the format's original refmod_meta key and also accepts ref_meta, which is the key used by earlier files saved here. So references from the original reference-node package and older saves from this pack both load, and the shorter node names didn't break file compatibility.

It is strict about contents, though. The file must contain exactly one latent tensor, floating point, with a shape that matches its declared kind: 24 channels for visual image/video references, 32 for audio, and shapes and dimensions in the header must agree with the tensor or the load fails rather than guessing. That strictness is good news - a corrupted or hand-edited file errors out instead of producing a quietly wrong reference.

Outputs are ref, which goes to MiniMax H3 Ref Apply (or back into Ref Save if you want a copy under a different prefix), and info, a string summary of what was loaded. info is worth reading once per project: it prints the kind, the latent shape and the token cost, which is exactly the number that decides whether your reference budget holds.

Install

Manager → search "ComfyUI-UtilsCollection", or:

cd ComfyUI/custom_nodes
git clone https://github.com/silveroxides/ComfyUI-UtilsCollection
# restart ComfyUI

Nothing downloads - this node only reads files you already have. The pack registers ComfyUI/models/minimax_h3_refs on load, so you don't need to create the folder; MiniMax H3 Ref Save writes into it, and standard ComfyUI extra-model-path configuration works if you keep your refs on another drive.

The pack-wide caveat, because it bites everyone installing for one node: requirements.txt lists opencv-python, huggingface_hub, unifiedefficientloader and typing-extensions, while the code imports kornia at load without declaring it. A missing kornia takes the entire collection down with an import error, so the fix for "I installed it and no nodes appeared" is pip install kornia.

The one annoying behaviour

The filename dropdown is populated when the pack's nodes register. Save a reference and the newly written file may not show up until you refresh the node definitions or restart ComfyUI. It's a UI staleness thing, not a broken save - the file is in ComfyUI/models/minimax_h3_refs and the saved paths output from Ref Save tells you exactly what it's called.

The other one is portability. A workflow that loads a reference by filename is only portable as far as that filename: share the graph without the .safetensors and it loads fine, then fails at queue time with a missing-file error. If you're handing a workflow to someone, hand them the refs folder too.