MiniMax H3 Combined Model Loader

If you've poked at MiniMax H3 in ComfyUI, you already know the awkward part: the diffusion checkpoints arrive split. There's the FL2VA one, which does image-to-video from a start frame and optionally an end frame, and the REF2VA one, which does reference-driven generation - show the model who the subject is, get video of the subject. Both are genuinely useful. Both are also only half of what most people actually want, which is a clip that starts from your image and honors your references in the same pass.

This node is the answer to that fork. It's one loader that replaces two, and in its default mode it stitches FL2VA and REF2VA into a single combined model on the fly - no merged checkpoint to hunt down, no file written to disk. Think of it as a runtime LoRA-like splice, except instead of a LoRA file it's swallowing whole transformer blocks from a second checkpoint.

How the splice actually works

Combined mode is a straight tensor swap. The node opens both .safetensors files, verifies they have identical key layouts, then takes every tensor from FL2VA except the adaln_proj.linear weights and biases in transformer blocks 25 through 49, which come from REF2VA instead. adaln_proj is the adaptive layer-norm projection that injects conditioning into each transformer block, so the author's split argues that reference-identity conditioning lives in the later blocks of REF2VA - splice those in, keep the video behavior of FL2VA, get one model that does both.

The swap also carries over quantization sibling tensors (_scale, comfy_quant) with each selected weight, so fp8 and INT8-ConvRot checkpoints splice cleanly instead of leaving orphaned scales behind. And the merged dict goes through ComfyUI's own load_diffusion_model_state_dict, so you get a completely ordinary MODEL that plugs into your normal sampler setup.

One consequence worth knowing: the merge happens in system RAM on every load. Queue a job and you'll see a pause while a full model's worth of tensors is assembled before it hits the GPU.

The inputs you'll actually touch

fl2va_model and ref2va_model are dropdowns over whatever safetensors you've dropped in ComfyUI/models/diffusion_models - the same folder the stock Load Diffusion Model node reads, and the classic gotcha if you stashed your H3 files in an old checkpoints folder out of habit.

• load_mode - default "load fl2va+ref2va" is the whole point. Flip it to load either checkpoint standalone, and the node is just a good ordinary loader that carries the attention overrides too.
• ref_start_block / ref_end_block - the splice window, default 25–49. Only meaningful in combined mode; leave them alone unless you know what you're doing.
• weight_dtype - keep default. The fp8 options mirror the stock loader's overrides, but embedded quantizations like INT8 ConvRot want default - the quant metadata is already inside the files.
• attention and allow_compile - the dense-attention backend, covered next.

The attention menu is half the reason to install this

H3 is a big transformer, and dense attention is where the seconds go. The author's own timings: ~300s on the SDPA path, ~200s on sageattn_qk_int8_pv_fp8_cuda++ (SageAttention 2), ~185s on sageattn3. The catches: every SageAttention mode needs the optional sageattention package installed into your ComfyUI Python environment, the sageattn3 modes need the sageattn3 package and a Blackwell GPU (RTX 50-series), and allow_compile should stay off unless your setup explicitly supports torch.compile. No package installed? The node errors with a message that says exactly that - no silent fallback, no garbage output. If you can't run SageAttention at all, pytorch forces ComfyUI's SDPA path, which the README suggests pairing with the KJ MiniMax H3 memory-efficient Sage Attention patch node.

Installing it

Via ComfyUI Manager (search "MiniMax H3 Combined Model Loader"), or by hand:

cd ComfyUI/custom_nodes
git clone https://github.com/entropicnoise/MiniMax-H3-Combined-Model-Loader

Then restart ComfyUI. The pack ships zero hard dependencies - no requirements.txt, everything it calls is core ComfyUI - but the README warns you want a current ComfyUI (it names v0.33.x), because the loader leans on fairly new core loading paths and native INT8-ConvRot support. The actual work is downloading matching FL2VA and REF2VA checkpoints, in the same architecture and quantization format.

When it fights back

The sharpest failure mode is a hard error demanding matching checkpoint layouts. That's the key-set equality check refusing to run, and it almost always means you mixed formats - an fp8 FL2VA with a BF16 REF2VA, say. Reach for matching quantized pairs. If instead you get "No REF2VA AdaLN tensors were found in the selected block range," the window is empty or the pair genuinely isn't an H3 diffusion checkpoint.

Nothing to do with this repo, but it belongs in the paragraph: H3 weights ship under the MiniMax H3 Community License, which geofences local weights and their outputs out of the US, EU, UK and South Korea. This loader is just a loader - it's fine everywhere. Just check you're actually licensed to run the models in your region before you spend the download and the VRAM.