MiniMax-H3 Attention Mask Patcher

MiniMax-H3 is the open-weight video model of the moment - 33B, native stereo audio, ComfyUI support on day zero. The natural next ask, once you've got a character generating cleanly, is region control: keep the person, swap the background. This node claims to do exactly that by masking the model's self-attention. One problem: the way it does it is very likely a no-op on H3. Let me show you what I mean, because it's the difference between wiring this in and wasting an afternoon.

The pitch

The idea is sound and you've seen it before: instead of inpainting after the fact, bias the diffusion model while it samples so certain regions attend differently. Feed in a mask from SAM2 or RMBG, tell it to suppress the background or preserve the foreground, dial a strength, and out comes a MODEL you plug straight into the sampler. No training, no LoRA, no extra weights. It's the attention-masking family that regional prompting and reference-attention nodes live in - the same philosophy that gets you seamless background replacement in one pass rather than a compositing battle afterward.

How it actually works - and the catch

The node clones your MODEL, then installs an attn1 patch via ComfyUI's set_model_attn1_patch API. Inside that patch it does two things: blends the mask toward neutral by strength (suppress_background pulls background values toward zero, preserve_foreground pulls them toward one), then multiplies the attention queries by the flattened mask values.

Here's the thing. In ComfyUI, attn1_patch is consumed in exactly one place: the classic SD1.5/SDXL UNet cross-attention block. MiniMax-H3 is a DiT, and like Wan, LTX and Hunyuan before it, its ComfyUI attention path doesn't consult that hook. The people who built H3's actual sparse-attention kernel (the H3-SLA pack) documented this precisely: a patch installed there "reports success and silently does nothing." So while I can't promise it never fires in some future ComfyUI version, the working assumption should be that this node installs, runs without error, and changes nothing on H3. Verify it with an A/B run before you trust any claimed effect - same seed, node in the graph vs. bypassed, compare the frames. If they're identical, that's your answer.

Two more honest knocks on the mechanism. The custom_bias mode is in the dropdown but the code never actually branches on it, so it behaves like the others. And the mask-to-token mapping is crude: it flattens your [B, H, W] or [B, F, H, W] mask and multiplies query tokens positionally, which assumes the mask grid lines up with the latent token grid. It usually doesn't for video, so shape errors are a realistic failure mode.

The inputs that matter

Only four, and they're all required:

• model - the MODEL output from your MiniMax-H3 loader. Wire the patched output into your sampler.
• mask - a MASK. Foreground person = 1.0, background = 0.0, so a SAM2 or RMBG segmenter output works as-is.
• strength - float slider, 0.0–1.0, default 0.8. The author recommends 0.75–0.85 for smooth camera motion and background replacement.
• mode - suppress_background, preserve_foreground, or custom_bias (see above: the last one isn't implemented).

One output, MODEL, into your KSampler or SamplerCustomAdvanced.

Install

Single-file node, zero dependencies, no model downloads. Either search "ComfyUI-MiniMaxH3-AttentionMask" in ComfyUI Manager, or clone it:

cd ComfyUI/custom_nodes
git clone https://github.com/khwhite0413/ComfyUI-MiniMaxH3-AttentionMask

Restart ComfyUI, then right-click → MiniMax-H3/Attention → MiniMax-H3 Attention Mask Patcher. One footnote: the pack README's own install snippet says YourUsername instead of the real repo path - that's a copy-paste bug in the README, use the URL above. And remember the elephant in the room for any H3 work: the community license excludes the US, EU, UK and South Korea, so check you're allowed to run the weights at all.

What to actually do

Install it, A/B it, and if it's a no-op, don't fight it - that's not you failing, that's the patch hook being the wrong tool for a DiT. If you genuinely want attention surgery on H3, the path that does work is the optimized_attention_override route the H3-SLA node uses. This one is a reasonable idea shipped through the wrong mechanism. Cheap to try, worth knowing before you trust it.