Apply H3 RefLoRA References

This is the plain-vanilla half of the pack, and the honest description is: it exists so your workflow doesn't need a second custom-node pack to inject references. You've got H3_REF_MODS coming off the loader; this puts them into a MiniMax H3 conditioning.

If you already run ComfyUI-MiniMaxH3Mod, its Apply H3 RefMod node is richer - curves, scrambling, graph presets - and it accepts this pack's H3_REF_MODS output directly. The types are deliberately interchangeable. So think of this node as the zero-dependency option rather than the power-user one.

What it does mechanically

References reach an H3 model by two routes. Route A - this node - appends reference blocks to the conditioning's reference list, which the model reads as extra tokens alongside your prompt and your start frame. Route B is the loader's attach_to_model switch, which instead wraps the model so the blocks get folded in right before sampling.

Both end up in the same place at the same moment. The difference is bookkeeping: route A gives you an explicit node in the graph you can see and disable, route B gives you one wire and one less thing to mis-wire.

Worth knowing which route you're on for a dumber reason too. The packs this one interoperates with - ComfyUI's own MiniMaxH3ImageToVideo / MiniMaxH3ReferenceToVideo conditioning, and ComfyUI-MiniMaxH3's MINIMAX_H3_COND dataclass - use different field names internally (minimax_refs versus refs). This node detects which type it's been handed and appends to the right one, returning the same type it received. That's why you can drop it into a workflow built for the other pack without rewiring anything.

Inputs and outputs

Three required, one optional, one output. Not much to get wrong.

conditioning comes from MiniMaxH3ImageToVideo or MiniMaxH3ReferenceToVideo - the conditioning you'd otherwise send straight into your guider. mods comes from Load H3 RefLoRA. retention is a master reference strength that multiplies each row's own strength: 1.0 fully preserved, 0.4 attribute transfer, straight from the tooltip.

Here's the bit people miss. The loader already folds its own refmod_retention into each row it hands out, so this node's retention stacks on top of it. Loader at 0.7 and Apply at 0.4 gives you 0.28, not 0.4. Leave this one at 1.0 and do your dialling on the loader tube - or, if you want one global dial downstream of several loaders, set the loader dials to 1.0 and use this. Pick a lane; doing both compounds and the arithmetic gets annoying fast.

max_total_tokens (optional, default 0 = off) is the same guard as the loader's, checked against the blocks actually being injected. If a reference would push the total over the limit, the node raises before sampling rather than letting you discover it ten minutes into a render.

The single output is conditioning - wire it to your guider. Done.

Wiring it

Skipping the loader's model-attached route, a minimal graph looks like this:

MiniMaxH3ImageToVideo ──conditioning──┐
                                      ├──> Apply H3 RefLoRA References ──conditioning──> BasicGuider
Load H3 RefLoRA (LoRA + RefMod) ──mods┘
Load H3 RefLoRA (LoRA + RefMod) ──model─────────────────────────────────────────────> BasicGuider

The model output goes to the guider; the conditioning output goes to the guider. The info string off the loader is worth dropping into a Note or a Show Text node while you're tuning - it reports which members loaded and their token cost.

Install

Same pack, same install, nothing extra:

cd ComfyUI/custom_nodes
git clone https://github.com/malcolmamal/ComfyUI-MiniMaxH3RefLoRA

Restart, and it shows up under MiniMax-H3/reflora. No dependencies - this pack has no requirements file at all, which is refreshing in a niche where half the nodes you install want to reinstall torch.

Troubleshooting

References applied twice. If the references are attached to the model and wired through this node, you get both. The tell is a run that's noticeably slower and stickier than the reference strength suggests. Turn off attach_to_model on the loader, or disconnect mods - one or the other.

Nothing happens. Check the loader's refmod_retention and members first. Retention at 0 loads no references at all, members: none does the same deliberately, and the components filter can silently leave you with an empty set if the container's reference is audio and you asked for visual. The loader prints exactly this case to the console: references present, none selected.

You're on ComfyUI-MiniMaxH3Mod too. Nothing breaks, but don't stack this node and that pack's Apply node onto the same conditioning unless doubling your reference budget is the experiment. And if you hit token-budget errors, the cap counts what's actually in the conditioning - including anything the other pack appended.