MiniMax H3 Atomic FL2VA / REF2VA Model Router

MiniMax H3 isn't one model. In the IAMCCS Shotboard workflow you typically have a base FL2VA model (first/last-frame to video, the keyframe-anchored route) and a separate REF2VA model (reference-media to video). The atomic backend's job is to run a long multi-segment timeline where some segments want one and some want the other. Loading both into VRAM because a single segment needs one is exactly the kind of waste that OOMs you. IAMCCS_MiniMaxH3AtomicModelRouter is the lazy switcher: it reads the active task for the current segment and only the model branch that task needs ever gets selected - the docstring calls it "lazy model switch: only the branch required by the active H3 task loads."

Inputs are minimal: cine_linx (the bus carrying the shotplan and per-segment task), segment_index (which chunk you're on - the atomic pipeline drives this from a queue loop), and the two optional MODEL inputs fl2va_model and ref2va_model. Outputs are model (the selected MODEL), model_family (a STRING saying which family won), and report (a STRING).

How it decides: it looks up the current chunk in the shotplan, resolves the effective task - respecting the task_override logic upstream if one was set - and picks ref2va_model when the task is REF2VA-family, otherwise fl2va_model. If the family it needs isn't connected, it fails loudly with a message telling you to connect that branch. That's a feature: a silent fallback would feed a segment the wrong model and you'd burn a long render discovering it in the output.

The piece people miss is that this node is a selection, not a load manager. In ComfyUI, the MODEL you select is the one that gets loaded when the sampler pulls it - so "only loads what it needs" is achieved by never handing the sampler the other branch. Which is why it pairs naturally with the conditioning backend: the router hands the right model, IAMCCS_MiniMaxH3AtomicConditioningBackend builds the matching conditioning and AV latent for the same segment, and both key off the same segment_index.

The report output is your friend during setup: it tells you the resolved family per segment, so you can glance at a timeline and confirm "okay, segments 0-2 are FL2VA, segment 3 is the REF2VA retake" before committing to a long render.

Installation is pack-standard: search IAMCCS in ComfyUI Manager, or clone https://github.com/IAMCCS/IAMCCS-nodes.git into custom_nodes and restart. The models are yours, and the pack's MiniMax H3 workflow doc spells out the family: a T2VA/I2VA/FL2VA model plus the compatible REF2VA model, in full, pruned INT8, or GGUF variants - the router doesn't care about the variant, only the branch. It runs on a ComfyUI build with native H3 AV conditioning.

The failure mode you'll actually meet is connecting only one model and getting the hard "connect the ref2va_model branch" error when a segment is REF2VA. It means the timeline really does want a reference segment - either add the model, or fix the task assignment upstream. And don't be tempted to feed the same MODEL into both inputs; model_family will report honestly, but you'd be telling the router two different tasks use the same weights, which defeats the design.