BSAI FastH3 Loader (4-step / 8-step V2 / OmniRef)

There's a specific way people first break FastH3: they download a MiniMax-H3 checkpoint, pick it in a loader, run four steps, and get something that looks like it was rendered through a wet sock. Nine times out of ten they loaded the 50-step base model instead of the distilled FastH3 weights, because both are .safetensors files sitting in the same folder with names only a robot loves.

BSAIFastH3Loader exists partly because of that. It's a thin wrapper around ComfyUI's normal diffusion-model loader with a filename bouncer on the front, and once you understand what the bouncer is checking you'll stop fighting it.

What it actually does

FastH3 is FastVideo's data-free DMD2 distillation of MiniMax-H3 - the 33B omni-modal video model that generates a synced audio track in the same pass. The distillation collapses 50 denoise steps into 4 (or 8, in the newer V2 checkpoint), which is the whole reason a 33B video model is usable on consumer hardware at all. The price of that collapse is that the weights only behave on the noise-level ladder they were trained on, so weights and recipe have to match.

The loader picks the file, and when strict_fast_h3_check is on it also refuses files whose names don't contain the expected markers. Under the hood it just calls comfy.sd.load_diffusion_model with whatever dtype options you picked, so nothing exotic is happening - no custom weight surgery, no hidden quantization pass.

The four inputs

model is the dropdown of everything in ComfyUI/models/diffusion_models. That folder is the only place it looks, so if your file is in checkpoints the list will be empty and you'll think the node is broken.

weight_dtype has default, fp8_e4m3fn, fp8_e4m3fn_fast, fp8_e5m2. Leave it on default. The FastH3 files are already int8_convrot quantized, and the node warns you about this in the log if you pick fp8 anyway. Casting an already-quantized checkpoint down again buys you nothing and costs precision.

model_type is the useful one: auto, fast_h3_distill, base_h3_fl2va. On auto it accepts either a FastH3 distilled file or an original MiniMax-H3 base (minimax_h3_fl2va*, ref2va, hybrid). Pin fast_h3_distill when you want the node to hard-fail rather than silently load a base model, and use base_h3_fl2va only for the 3-step TaoMate recipe, which runs on the stock H3 base plus a LoRA rather than on distilled weights.

strict_fast_h3_check is on by default and validates the filename against model_type. The distilled markers it looks for are fastvideo, fasth3, fast_h3, 4step, 8step, v2; the base markers are minimax_h3_fl2va, minimax_h3_ref2va, minimax_h3_hybrid. Turn it off and it will load literally any H3-shaped file you point it at, which is exactly the mistake it was built to stop.

One output, MODEL. It goes into BSAIFastH3NativeVSA - that's the node that patches sparse attention and, for the 8-step V2 recipe, rewrites the model's video shift. Everything downstream (timesteps, guider, sampler) wants that patched model, not the raw one.

Install

ComfyUI Manager, search BSAI-ComfyUI-FastH3, or:

cd ComfyUI/custom_nodes
git clone https://github.com/xm6018924/BSAI-ComfyUI-FastH3.git

Then restart ComfyUI. There is no requirements.txt in the repo and no mandatory third-party dependency - the code imports torch, comfy and folder_paths and nothing else. The only optional extra is comfy_kitchen, which the VSA node uses for the fast sparse-attention kernel:

python -m pip install comfy_kitchen

Weights, in models/diffusion_models unless noted:

• minimax_h3_fastvideo_vsa_datafree_1300step_4step_int8_convrot.safetensors - the 4-step route, ~22.9 GB
• fastvideo_fasth3_8step_v2_pruned_int8_convrot.safetensors - 8-step V2, ~20.6 GB, the Comfy-Org repack and the one you want
• minimax_h3_fl2va_pruned_int8_convrot.safetensors - ~19.5 GB, only if you're doing the 3-step TaoMate recipe
• qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors in models/text_encoders
• minimax_h3_video_vae_int8_convrot.safetensors and minimax_h3_audio_vae_fp32.safetensors in models/vae

Where people get burned

The strict check's error message is unusually honest - it names the marker that was missing. If it says your filename lacks the distilled marker, you downloaded the base. Don't disable the check; grab the right file.

If the dropdown doesn't list a model you swear you downloaded, look for a .xltd suffix. A half-finished download keeps the temporary name, and the loader reports "model not found" for a 20 GB file that's sitting right there.

Use the int8 video VAE. The author's own test notes have fp16 video VAE decoding as snow and OOM on ComfyUI 0.36, which is a fun hour to lose when you assume the model is at fault.

And the boring one: new nodes need a ComfyUI restart to register, and old workflow JSONs still load even though this node grew a model_type widget - the missing widget just takes its default.

Last thing, and it's not the node's fault: MiniMax-H3 ships under a community licence that excludes the US, EU, UK and South Korea. If you're in one of those places, the hosted API is the licensed path - the loader will happily load weights you aren't cleared to run.