MiniMax H3 Ref Save

Reference conditioning is only pleasant when you're not re-deriving it every run. That's the whole job of UC_MiniMaxH3RefSave: take the reference latents you extracted from images, video frames or audio, and write each one out as its own .safetensors file so the next workflow can just load it.

Two reasons this matters more than it first sounds. Encoding a reference means running the H3 VAE, which for a video reference is not free. And a reference you saved in March is a reference you still have in June - unlike an in-memory object that dies with the queue.

What gets written

refs is an autogrow input, so you can stack multiple references on it (the sockets are generated for you). Each connected reference is saved separately, in input order - four refs in gives you four files out, not one bundle. Order matters, because the reference order you later apply them in is the order the model sees.

filename_prefix defaults to ref/MiniMax_H3, and the slash is doing real work: it creates a ref subfolder. ref/MiniMax_H3 becomes a path like this, relative to the ref root:

ComfyUI/models/minimax_h3_refs/ref/MiniMax_H3_0001.safetensors

Files are numbered automatically with a four-digit index, and existing files are never overwritten - saving again moves you to the next free number. That's deliberate, and it's the reason re-queueing a workflow doesn't quietly destroy the reference you liked.

The output is saved paths: a list of strings with the relative filenames, including any subfolders. Wire it into a text or display node if you want to see where things landed.

Output node, on purpose

UC_MiniMaxH3RefSave is an output node, and that is a real workflow convenience: you can queue extraction-and-save on its own, without a sampler downstream, and without ComfyUI complaining about an unconnected output. Extract all your reference images once, save them, then go back to building the actual generation graph and load what you need.

Each file stores the reference latent plus a metadata header - the same refmod_meta key the original reference format uses - holding the description, source, kind, compression settings and dimensions. That metadata is retained for your benefit, not applied automatically: a saved description does not become a prompt, and saved compression settings are a record of how the reference was made, not a control that will re-apply itself on load.

Install

Manager → search "ComfyUI-UtilsCollection", or:

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

The pack registers ComfyUI/models/minimax_h3_refs for you; you don't need to create it first. No models download for this node. The usual pack caveat applies - requirements.txt covers opencv-python, huggingface_hub, unifiedefficientloader and typing-extensions, but the collection imports kornia at load time without listing it, so a missing kornia means none of the pack's nodes appear at all.

The saved artefacts live under ComfyUI/models/minimax_h3_refs, which means they're model files as far as ComfyUI is concerned - back that folder up, and expect workflow-sharing etiquette to apply. Someone else's workflow references filenames, not the latents, so a shared graph without the ref folder is a graph that loads and then fails at Load.

Traps

Two worth knowing. First, the prefix is a path, and it's validated to stay inside the ref folder - ../../something won't escape. Fine, but don't be surprised that an absolute-looking prefix doesn't behave like one.

Second, and more annoying: MiniMax H3 Ref Load's dropdown is built from the folder contents when the nodes register. Save something new and it may not be listed until you refresh the node definitions or restart ComfyUI. The file is on disk and correct; the list is just stale. The saved paths output tells you the filename, and a refresh makes it selectable.