Add Qwen Image Reference for MiniMax H3

MiniMax H3 is an omni-modal video model: it reads text, images, video, and audio as one context, and people are already using its reference-video path for the kind of object replacement that used to mean a LoRA. The catch is that its native image/video references are a scarce resource - they get VAE-encoded and burn real structure slots. This node is the cheat: it shows an image to H3's built-in Qwen vision encoder as a plain, tagged <Picture N> token, and you refer to it in your prompt as #red_car. No VAE encode, no native slot consumed, no extra model download. You effectively get unlimited "here's what this thing looks like" references for the price of some vision tokens.

How it works

Sit the node between the MiniMax H3 CLIP loader and the core MiniMax H3 Reference to Video node:

H3 CLIP
  -> Add Qwen Image Reference
  -> MiniMax H3 Reference to Video

At tokenization time, the node finds the next free H3 <Picture N> number, swaps your #tag for it, and hands the image to Qwen exactly once. It doesn't touch minimax_refs, so your native image/video/audio references keep working normally alongside it. The patch only activates through the core Ref2VA tokenizer path - any other CLIP workflow passes through completely unchanged (which is also how you get burned, see below).

Chain several of these to give the model a whole cast. One example workflow in the repo compares the same street-race scene described with text alone versus described with #red_car and #blue_car image references, and the difference is the whole point of the node.

The inputs that matter

There are only three you touch, and two of them are easy:

• clip - the H3 CLIP model. If you feed it a non-H3 CLIP, the node raises "Qwen references require the MiniMax H3 CLIP model." It's a hard error, not silent.
• image - the reference picture. It's not VAE-encoded; it's read semantically, like a caption the model can actually see.
• prompt_tag - the name you write in the Ref2VA prompt with a leading #. Default anchor. Must start with a letter and contain only letters, numbers, _, or -. Keep it unique across the chain - chaining two nodes with the same tag is an error.

image_size is the one with a trap in it. 64 is Qwen's practical aligned floor in this path but carries almost no visual detail - use it and you might as well have described the thing in words. 256–512 is the sweet spot; go lower only when the subject still reads and you're counting vision tokens. source keeps your input resolution untouched. Resizing is done to multiples of 32 with lanczos, so a wonky input gets tamed either way.

Install

Grab it through ComfyUI Manager by searching MiniMax H3 Timed References, or:

cd ComfyUI/custom_nodes
git clone https://github.com/ethanfel/ComfyUI-MiniMaxH3-Timed-References.git

Then restart ComfyUI. There's no requirements.txt and no bundled model downloads - the node leans entirely on core ComfyUI's H3 support (comfy.text_encoders.minimax), so you need a reasonably recent ComfyUI and the H3 weights loaded normally. The pack is GPL-3.0-only and still alpha (v0.3.0), so pin your expectations accordingly.

Where people get burned

The big one: this node looks like it's doing something on any CLIP line, but it only has teeth on the H3 Ref2VA path. Wire it somewhere else and it silently passes through - no error, no reference. Also remember H3 itself isn't unconditionally open: the H3 Community License excludes the US, EU, UK, and South Korea from running the local weights at all, and this node is useless without them. The node is fine; the model underneath has a map attached. For everyone else, think of the untimed version as your default for a hero image or a single subject, and reach for the pack's timed image/video references when the picture has to show up at a specific moment in the clip.