Fantastic H3 Reference Cache (experimental)

MiniMax H3 is a 33B omni-modal video model, and it's slow the way a 33B model with an audio branch is slow. In reference mode - a character RefMod, a motion clip, a voice - much of every step goes to work that barely changes between steps. This node is the author's attempt to skip it.

MiniMaxH3FantasticReferenceCache sits between the model loader and the sampler, takes a MODEL, hands a patched MODEL back, and makes H3 reuse the reference rows of its packed sequence from one step to the next. It shipped in 1.8.3, is labelled experimental in the node name and in its own description, and the author is upfront that it changes your output. Believe that part.

Why you'd reach for it

H3 packs prompt, references, audio and video into one sequence and runs the lot through every block with full attention. At the end it reads only the audio and video rows; the reference and prompt rows exist to be attended to. So those rows are dead weight on every step but the first, and the node bets you can refresh them occasionally instead of every time.

It's a small bet for a small win. The changelog's one measurement is 4–15% faster per step, on reference-mode runs. That's not the "twice as fast, can't tell" shape people got used to from TeaCache on Wan - think shaved minutes on long renders, not a free resolution tier.

How it works

On a refresh step, every block runs normally and copies its input for the cached rows into system RAM - pinned when ComfyUI's budget has room without evicting the model's own pinned weights. On the steps in between, each block rebuilds those rows' keys and values from the stored copy, so they skip their attention query projection, output projection and MLP. Only the video and audio rows do full work.

It's a MODEL patch: the node clones the model, replaces the double_block pass on every DiT block, and wraps the sampling run so the RAM buffers are freed at the end. It's tracked per conditioning layout, and where there's no contiguous run of cacheable rows it steps aside and runs the normal block. No extra VRAM - the cost is RAM, printed in the console on the first call. The release notes give ~2.5 GB for a 6-frame RefMod, half that with store_8bit.

The inputs that matter

You touch two, and you should respect both.

• model - H3 loader in, sampler out, same slot a LoRA loader would take. Anything that isn't H3 gets Connect a MiniMax H3 model.
• cache - references (default) caches reference images and audio plus the conditioning rows behind RefMods. references and prompt also freezes the text side, which as the author notes can be as many tokens as the references: more speed, more approximation. Leave it on the default unless you're deliberately pushing.
• refresh_every - default 2, range 2–16. The cached rows run in full on the first call and every Nth after it. Higher is faster and drifts further. Start at 2.
• store_8bit - keeps the cache as fp8 with a per-row scale: half the RAM, half the copying, values "typically 2-3% off" between refreshes by the tooltip's own estimate. Fine on any GPU ComfyUI can store fp8 weights on; MPS and DirectML are out, and it errors (This device can't store 8-bit floats) rather than silently falling back.

One output, MODEL, into the sampler or whatever else patches the model downstream.

Install

Nothing extra to fetch - it comes with the pack:

cd ComfyUI/custom_nodes
git clone https://github.com/Adudeguyman/ComfyUI-Fantastic-MiniMaxH3-PromptBuilder

Or search "Fantastic H3 Prompt Builder" in ComfyUI Manager, then restart ComfyUI properly, not just the browser tab. You need ComfyUI 0.30.0 or newer, the H3 checkpoints (ref2va for reference mode - the only place this node does anything), and PyAV, which core already requires. It appears under conditioning → video_models as Fantastic H3 Reference Cache (experimental).

Where it bites

The node may simply not be there. The pack imports ref_cache inside its own try/except so an experimental failure can't take the RefMod nodes down with it. If it breaks you get a console line - [MiniMaxH3] Reference Cache unavailable: … - and nothing in the menu. Check the startup log before blaming Manager.

Your output changes, deliberately. Between refreshes the reference rows never see the video move. If you're iterating on a prompt and add this halfway through, you've moved your own goalposts. Bypass the node (Ctrl+B) for the untampered run; it passes MODEL straight through, so the A/B is clean.

No references, no benefit. Text-to-video on fl2va gives it nothing to cache, so you'd pay patch overhead for nothing.

And don't stack the knobs blind: refresh_every up, store_8bit on and references and prompt each add approximation. Change one at a time, or you won't know which one cost you the face.

It's the only H3 speed knob in this pack that changes the numbers rather than the graph. The author's own advice is the right test: run it, bypass it, compare.