H3 Image Reference

Why you'd reach for it

First-frame/last-frame conditioning is the oldest trick in video generation for getting from A to B instead of from A to somewhere - Wan 2.1 shipped a dedicated FLF2V model for it, and LTX has supported start-and-end keyframes since 0.9.5, where the community found that conditioning on a middle or end frame makes the model guess less and move more.

H3 Image Reference does that for MiniMax H3, and it also does the plain job of naming a picture so you can @mention it in a scene prompt. One node, two modes, no mode selector - you pick the role and the main node works out the rest.

How it works

source is Connected input or Load file; Load file reads straight from disk and disables the batch-selection controls, because a file isn't a batch. batch_selection defaults to all and takes batch positions, so you can pull one frame out of a generated batch.

role covers the ordinary reference jobs - character appearance, association, wardrobe, scene, prop, style, custom - plus the two endpoint roles. The role drives the guidance H3 receives: scene tells it to use the environment but not the people in it, style transfers visual style without copying identities, prop uses the object, and so on. associated_character binds the reference to a character alias so the picture counts as that character's evidence.

descriptor is what actually gets written into the prompt: @tag expands to your description followed by the Picture or Video reference label. There's a real constraint - plain text only, no @tags, no H3 labels, no newlines - and it's enforced, because otherwise you could smuggle the whole prompt through a descriptor field and the compile order would stop making sense.

reference_type is the preservation knob, with four settings and no ambiguity about what they mean: fully_preserved keeps the defined content, partially_preserved allows selected changes, attribute_transfer applies features to another subject, weak_reference keeps broad resemblance. retain and change fill in the specifics; blank retain means "use the role's default guidance."

Outputs are named_reference (H3RC_REFERENCE, into the main node's named-reference sockets), selected_images (the actual batch that was sent), and selection_report.

First and last frame

Set role to First frame or Last frame, connect the output to H3 Mod Reference to Video, and use the @tag in your shots. One node per endpoint - connect two of these nodes and the main node detects the pair automatically, labelling them as a hybrid of opening/ending keyframes plus ordinary references. The README offers @opening and @ending as the conventional tags.

Three things bite here. First, endpoints require exactly one selected image, so batch_selection must resolve to a single frame - all on a four-image batch is an error, not a coin flip. Second, a full H3 visual VAE is required even if your saved profiles are Direct-references-only; the error text is literally "First/last frames require the full H3 visual VAE." Third, endpoint images are resized proportionally and centre-cropped to fill your output dimensions, so check the aspect ratio you're generating at - a square image into a 1344×768 generation loses its top and bottom.

On the prompt side, endpoints change what text H3 sees. You keep writing summary, detailed_description (with optional [Shot N] markers), overall_soundscape and non_diegetic_music; the node compiles endpoint-only prompts into integrated_multimodal_description with native opening/ending alignment. You can author that field directly instead, but you can't supply both - the compiler raises on seeing them together. The ending image is anchored to the actual final frame after native frame-count alignment, so length (124 frames at 24fps is about five seconds, and the trained range is roughly 124–362) is what decides where "the end" is.

Install

ComfyUI Manager → search WorkflowX Configurator, or:

cd ComfyUI/custom_nodes
git clone https://github.com/haroonaslam/WorkflowX-Configurator
cd WorkflowX-Configurator && pip install -r requirements.txt

Restart, hard-refresh. The pack's dependencies are light (PyWORLD, numpy, scipy); the heavy lifting is ComfyUI's own H3 support and the H3 weights, which are large - a reported ~42.5 GB for the full-precision set - and geofenced: the Community License excludes the US, EU, UK and Korea.

Where it goes wrong

Manual budgeting includes endpoints, so switching to Manual on the main node with two endpoint images attached can trip the token budget before text encoding even starts. The node refuses rather than dropping anything, which is the behaviour you want and also the reason a run "does nothing" sometimes.

And if you want the same picture as both an endpoint and an ordinary reference, use two separate nodes - one image reference can't be both, and forcing it produces a reference count you didn't intend.