DiffusionGemma H3 Reference Context

MiniMax H3's Ref2VA mode doesn't just take a prompt - it takes a contract: a strict <Picture 1> / <Video 1> manifest describing what each reference asset is allowed to transfer (identity, style, motion, never the other way around). Hand-writing that manifest is where Ref2VA workflows go to die. DiffusionGemma H3 Reference Context is the node that binds your ordered assets and that role manifest into a single DG_CONTEXT - the same context type the Context Hub produces, but Ref2VA-aware.

There's a one-line rule that saves the most confusion: never use this node for LTX. It declares H3 Ref2VA asset semantics, and the LTX-2.5 readiness gate rejects it on purpose. LTX uses the ordinary Context Hub. This node exists for the MiniMax-H3 Ref2VA path, wired upstream of the H3 Target Profile and CoT Generator.

What goes in

• user_prompt - your creative brief.
• reference_manifest - one role per connected Ref2VA asset. The default is a sensible single-identity contract: <Picture 1>: [dg:identity,appearance] protagonist identity, face, hair, body, wardrobe, and distinguishing traits; preserve fully. The [dg:...] annotations are host-owned categories; strict Grounding Guard requires one on every Picture/Video role. They're stripped before compilation and never enter the H3 prompt.
• reference_images - an ordered image batch for DiffusionGemma to inspect. Batch item 1 maps to <Picture 1>, item 2 to <Picture 2>, and so on. Connect the same images separately to MiniMaxH3ReferenceToVideo - this node only feeds Director's analysis; the native node needs the pixels itself.
• reference_video - optional, inspected as <Video 1>. The native H3 node still needs its 24-fps frame batch connected separately.
• visual_description - optional text you can inject.
• reference_manifest_preset - custom uses your editable manifest; the presets (1 image - all visual attributes, 2 images - subject + environment/style, plus two contact-sheet layouts) avoid retyping common contracts. A selected preset overrides the text box at execution time, and the effective manifest shows up in the context_preview output.
• expected_subject_count - 0 is Auto. A positive value demands exactly that many consecutive semantic <Subject N> definitions. This counts semantic subjects, not pictures or reference sockets - one Picture can supply several tracked Subjects, and several Pictures can feed one Subject.
• sample_fps, max_duration_seconds, max_frames, overlong_policy (trim/reject) - how much of a reference video DiffusionGemma samples for its analysis.

Outputs: gemma_context (the DG_CONTEXT that flows to the Target Profile / Director), plus context_json and context_preview so you can eyeball the manifest before paying for a generation.

What Director does with it

Ref2VA output follows MiniMax's six-section contract exactly - subject_definitions, summary, retention_analysis, detailed_description, overall_soundscape, non_diegetic_music. <Subject N> means reusable visible content abstracted from assets, not an attachment number. Annotations must stay aligned with native H3 ordering: all pictures first, a paired video soundtrack labeled immediately before its video, standalone audio after. Director supports the native limits of nine pictures, three videos, three paired soundtracks, and three standalone audio inputs, and deliberately blocks an audio-only manifest because Ref2VA needs at least one visible reference.

Installing it

One of 55 nodes in exportAnything/ComfyUI-DiffusionGemmaPromptBuilder:

cd ComfyUI/custom_nodes
git clone https://github.com/exportAnything/ComfyUI-DiffusionGemmaPromptBuilder

or ComfyUI Manager → DiffusionGemma Prompt Builder. The pack-wide requirements install with it; the model you must fetch yourself is nvidia/diffusiongemma-26B-A4B-it-NVFP4 into ComfyUI/models/LLM/.

Common issues

• "Connected reference undeclared" blocks. If a picture is connected to the native H3 node but has no manifest role (or no [dg:...] annotation under strict grounding), validation fails closed. Keep the manifest in exact sync with the socket order.
• Wrong subject count. expected_subject_count trips when your manifest implies multiple semantic subjects - contact sheets and multi-entity shots are the usual culprits. Set it to the actual count or leave it at Auto.
• Mismatched sizes. For two differently sized reference images, run DiffusionGemma H3 Reference Pair Prep before the native reference sockets with MiniMaxH3ReferenceToVideo.ref_image_size=match, or H3 will handle the size difference worse than you'd like.