MiniMax H3 Image Reference (Plan v2)

Drop the same photo into H3 twice and you can get two completely different behaviors: once as an exact opening frame the model must reproduce, once as reusable identity it should reference throughout the clip. H3's own prompt guide makes this distinction, and the single most common mistake in hand-written H3 prompts is not telling the model which one a picture is. Image Reference (Plan v2) exists so you never have to - you pick the relationship, and the pack's compiler decides the native route and writes the correct H3 label.

The key idea is that one real image gets exactly one declared role, and the role decides everything downstream. There are two families:

• Pictures - Exact first frame, Exact last frame, Concrete keyframe / composition anchor, and Storyboard / shot planning. These stay in the native I2VA/L2VA/FL2VA route. The model reproduces or anchors on them directly.
• Reusable content - Define reusable visible content. This creates a Subject (a stable alias like "woman" or "truck") that the compiler numbers later as <Subject N>. This is the route for identity, wardrobe, objects, scene, style.

The inputs that matter

• image - exactly one image. Image batches are intentionally rejected; that's a deliberate guardrail, not a bug.
• image_use - the role above. This is the decision everything else hangs on.
• reference_name - a human-readable asset name for previews and errors. Name it like you'd name a layer.
• description - visible source facts or the exact composition to preserve. This is what actually steers H3, so write real detail, not "the image."
• content_type - required only for reusable content: Identity/appearance, Object/prop, Scene/environment, Visual style, or Pose/action.
• subject_name - the stable alias, only for reusable content. The compiler converts it to a final <Subject N>.
• retention - auto-picks per relationship: full preservation for identity/object/scene and exact frames, weak reference for style/storyboard, transfer for action/motion. You can override.
• shot_scope - optional numeric scope. Scoped Subjects must be cited in those shots' descriptions.
• transfer_target_subject - only for attribute_transfer: the target Subject must already exist upstream in the chain.

Outputs

• h3_plan - continue the chain from here.
• reference_handle - feed this to Subject Binding when one image defines additional Subjects or roles.
• h3_image - the image itself, carried through for the native route.
• reference_preview - the provisional Picture number, relationship, Subject alias, and scope. Read it once to confirm the role you meant.

Install and one real-world note

cd ComfyUI/custom_nodes
git clone https://github.com/ethanfel/ComfyUI-MiniMax-H3-Guide

Restart, look under MiniMax H3 → Plan v2. No extra dependencies. The pack has a helpful Reference Sheet system (separate nodes) for building reusable image/audio libraries you can pull from without hunting through your input folders.

Two gotchas worth remembering. First, H3 caps references hard: 9 images, 3 videos, 3 audio clips, 12 mixed files total - the pack validates against this rather than letting you exceed it silently. Second, don't describe a reusable identity Subject and then never cite it in a Shot: the compiler will flag the dangling Subject. That check is annoying until it saves you from an H3 prompt where the model just... picks a random face, because the prompt forgot to say who was on screen.