MiniMax H3 Reference Budget [Experimental]

H3 is an omni model: your prompt is a packed transformer sequence where text tokens, conditioning/reference media, audio, and video all share one row budget. In ComfyUI that means your reference image gets flattened into rows of tokens and becomes part of the sequence length - and when a high-res reference is big, those rows aren't free. MiniMax H3 Reference Budget is the experimental node that watches how many rows your direct reference is eating and, if you ask, caps it.

The honest framing: this is a diagnostic/research node, not a daily-driver. You will not need it to run a normal flow-aligned or progressive workflow. What it's for is understanding and bounding the cost of the reference segment of H3's text | conditioning/reference | audio | video layout - a topic that matters the moment someone hands you a big-reference workflow and your sequence blows past comfortable lengths.

Three modes, and they're all honest about what they do. native passes your conditioning through untouched (identity). diagnostic reports how many direct-video rows the reference currently occupies without changing anything - this is the one to start with, because it answers "how big is this thing, really?" decoupled_direct_experimental actually applies the guarded cap: if the direct reference's row count exceeds max_direct_video_rows (default 2048), it shrinks the direct video reference spatially until the rows fit. The cap scales the video down and snaps to even spatial dimensions, and it'll refuse a budget so small that one spatial patch per frame wouldn't fit.

Outputs are the (possibly resized) conditioning plus an H3_REFERENCE_REPORT with the before/after row counts, audio rows, and how many references were changed - so in diagnostic mode you get the numbers, in experimental mode you get the numbers and the change.

The limitation you need to internalize: this node cannot retroactively change reference tokens that have already been encoded into conditioning by the vision encoder. Whatever Qwen3-VL (H3's encoder) produced upstream is fixed; the budget only operates on the downstream direct-reference video representation. So it caps what you're about to feed the model, not what the encoder already spent.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/xmarre/MiniMax-H3-Flow-Aligned-Regenerate.git

Restart. No extra dependencies or models.

Bottom line

Reach for this when you're profiling a reference-heavy workflow and suspect the direct-reference rows are the problem - run diagnostic first and read the report. The experimental cap mode is clearly labeled as exactly that: an experiment, not a vetted quality path. This is also very much a "0 impressions on the search index" niche node from a single-author research pack, so treat the mode names as the author's own contract and verify effects on your own decoded media rather than trusting a default.