MiniMax H3 Segmented Conditioning V2

MiniMax H3's whole pitch is unified context - text, images, video and audio going in as one input rather than audio getting bolted on afterwards. Practically, that means the conditioning you hand it is pickier than the usual CLIP-text-encode blob: an image can be a positional keyframe at a specific frame index, or a persistent non-positional reference, and those are two different payloads that H3 expects in two different workflows.

MiniMax H3 Segmented Conditioning V2 builds exactly one of them, on purpose. It's the third node in Eclipse's V2 trio (Planner V2 → Plan Step V2 → this), and it's where a task gets its prompt and its picture.

How it works

For FL2VA (fl2va_keyframes), the node resizes the active original image to your generation canvas - stretched, deliberately, because it's a positional keyframe rather than a composition reference - and tokenizes the prompt with that image as <Picture 1>. If the task has a real bridge destination or an experimental endpoint, the endpoint goes in as a second image using aspect-preserving cover resize and centre crop, and the pair is tokenized in source-then-destination order. Each positional image is VAE-encoded and attached as minimax_keyframes at the local frame index that Plan Step V2 handed over. That's how a task can start on image A and land on image B at an exact index.

For Ref2VA (ref2va_active_reference), no indices exist at all. The active original image is the only reference, it's passed through the tokenizer as minimax_ref_items, VAE-encoded into one immutable minimax_refs block, and then it stays available for the entire task. Aspect ratio is preserved and nothing is ever upscaled: match scales the reference toward your generation canvas area, max allows up to a 2048-pixel short edge at a real premium in encoder time and sampling cost. If your prompt doesn't already name the picture, a one-line role sentence gets prepended so the model knows what that block is for.

The families are mutually exclusive and enforced - the node never produces both, and it rejects combinations your checkpoint can't handle.

Inputs that matter

• clip and vae - the matching H3 text/vision encoder and the H3 VisualVAE. Mismatched or generic encoders are the fastest way to get nonsense.
• prompts - this one is a link-only input. It wants String Multiline List's string_list output: non-empty lines map to your images in order, and an unavailable index falls back to line 0, so a single line applies everywhere. Blank lines are ignored.
• prompt_index - comes straight off Plan Step V2. A bridge keeps the source prompt; the destination's prompt starts only at the transition.
• source_image, has_start_guide, start_guide_frame_index, has_last_image, endpoint_frame_index - the picture and the positional slots, all of it from Plan Step V2. Don't pass these by hand unless you're writing the plan yourself.
• last_image (optional) - the bridge destination or the experimental hidden endpoint. Ignored entirely when has_last_image is false.
• width / height - the generation canvas, 1344×768 by default. It's the geometry the keyframes get fitted to.
• ref_image_size - Ref2VA only: match or max.

There's also an optional segment_plan + task_index pair. Connect both and the node can append the technical camera-cut instruction on exactly the eligible task; connect neither and you keep plain prompt behaviour.

Output

One output: positive, a CONDITIONING containing either minimax_keyframes or minimax_refs - never both. It goes into the positive slot of the H3 sampler path. You still supply your own negative from wherever you normally get one; this node doesn't touch it.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/r-vage/ComfyUI_Eclipse
pip install -r ComfyUI_Eclipse/requirements.txt

Or grab "ComfyUI Eclipse" from ComfyUI Manager and restart; the declared dependencies are ordinary (torch, numpy, Pillow, opencv-python, safetensors, torchvision, PyYAML, aiohttp). You do need H3 weights, and the weights family is the thing to get right before you touch the graph.

Where people get burned

• The family has to match the checkpoint. conditioning_family isn't a style choice; Ref2VA weights and FL2VA keyframes don't mix, and the node will tell you so rather than silently producing mush.
• Don't expect frame 0 to be your image in Ref2VA. It's a semantic reference for identity, texture and composition - it doesn't place a frame. With warmup in the plan, the visible opening frame is generated, not copied.
• endpoint_frame_index must be -1 when there's no endpoint, and a real endpoint index has to be non-negative. Passing your own values instead of Plan Step's is the usual cause.
• task_index requires segment_plan. Connect both or neither.
• max sizing is not free. A 2048-pixel short edge on the reference costs you encoding and sampling time for a modest fidelity gain; start on match.