Add Timed Image Reference for MiniMax H3

MiniMax H3's core Reference to Video node already accepts reference images, so you might wonder why this node exists. The answer is that it does something genuinely different: instead of VAE-encoding your image into a native reference block, it hands the image to Qwen - H3's vision-language half - at a specific timestamp, as pure semantic context. Think of it as tucking a picture into the text prompt. It's not conditioning the diffusion model on a reference frame; it's telling the language model "this is what the thing looks like, at this moment."

That distinction matters because native reference slots are finite and expensive. H3's timed references, by contrast, don't enter minimax_refs at all and don't consume a native slot. The classic use is identity anchoring: the pack's example workflow renders the same street race twice, once describing two cars entirely in prose and once handing Qwen #red_car and #blue_car images at 0.0s, to see which keeps each car's paint and silhouette distinct once the action starts. It's the "show, don't tell" version of a subject description.

How it works

The node sits on the H3 CLIP line, between the H3 CLIP loader and core Ref2VA. When you give it a prompt_tag like red_car, you write #red_car inside the Ref2VA prompt. At tokenization time the node:

• counts the native <Video N> references already attached to Ref2VA and assigns this one the next free label;
• swaps your #tag for that label in the prompt;
• presents your image to Qwen at the chosen time_seconds, duplicated into a two-frame pair (Qwen vision reads frames in pairs);
• keeps sub-second timestamps to six decimal places instead of H3's default rounding to tenths of a second.

Mechanically it clones the CLIP and wraps the tokenizer, so it only does anything on the core H3 Ref2VA tokenizer path - every other CLIP workflow passes through byte-for-byte unchanged. If the tokenizer isn't a MiniMax H3 tokenizer, it refuses loudly.

The inputs that matter

• clip - the H3 CLIP from your H3 CLIP loader. Non-negotiable, it must be H3.
• image - any IMAGE. Only the first frame is used.
• prompt_tag - default anchor; write #anchor in the Ref2VA prompt. Each tag in a chain must be unique, and it has to start with a letter (letters, numbers, _, - only).
• time_seconds - where on the generated timeline this reference applies. Default 0. Sub-second values are preserved, which is the whole point of this pack.
• image_size - combo from 64 to 1280 plus source, default 512. It's an approximate pixel-area target (the image is scaled so its total pixels ≈ size², rounded to multiples of 32). 64 is the technical floor but carries almost no visual detail; start at 256–512 and only go lower when you're pinching vision tokens.

The single output is a CLIP - wire it forward, chain more timed nodes (each with its own tag) for multiple anchors, then into the core MiniMax H3 Reference to Video node.

Install

In ComfyUI Manager, search for MiniMax H3 Timed References and click Install, or:

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

Then restart ComfyUI. No pip dependencies, no model downloads - this pack ships zero weights. What it requires is that you already have ComfyUI's core MiniMax H3 model set (the Comfy-Org/MiniMax-H3 files, including the Ref2VA model and H3 CLIP), because it leans on comfy.text_encoders.minimax internals. The code is GPL-3.0.

Where people get burned

• "Timed references require the MiniMax H3 CLIP model" - you wired a non-H3 CLIP into it. It's picky by design.
• Duplicate prompt_tag - every chained node needs its own tag; the chain rejects repeats.
• Timestamps past the video length - keep every time_seconds inside the generated clip's duration or the reference just floats in void.
• Wrong expectations - this is a semantic hint, not a pixel-level reference. For real frame-accurate identity transfer you still want H3's native VAE reference path; this node is for nudging Qwen's reading of the scene without spending a slot.

One thing to flag even though it's not about the node: H3's open weights ship under a community license that's void in the US, EU, UK, and South Korea. This pack is just code - but you need the model to use it, so check where you're standing.