(Deno) MiniMax H3 Multi Reference Image Loader

MiniMax H3 is the open-weight Hailuo successor that landed in ComfyUI as a native workflow in 2026: a multimodal video model that takes text, reference images, reference videos, and even reference audio, and returns video with native sound. The stock H3 "Reference to Video" workflow is genuinely powerful - and its reference-image handling is where the stock UX gets fiddly. (Deno) MiniMax H3 Multi Reference Image Loader is the fix: one cable, up to nine ordered reference images, each keeping its own size and aspect ratio.

Why does that matter? A normal ComfyUI IMAGE batch is a single tensor, which means every frame in it shares one width and height. The stock H3 input slots are Autogrow image connections, and once your references have mixed sizes - a portrait face shot next to a landscape product shot - something has to be resized or letterboxed to make them fit the shared batch. This loader sidesteps the whole thing with a dedicated bundle type that preserves each image's decoded dimensions and ratio, so your portrait reference stays a portrait.

How it works

The node is the loader half of a deliberate pairing with (Deno) MiniMax H3 Reference to Video. You manage the images through the node UI - upload, paste, drag-and-drop, browse the Input Folder, reorder the cards, clear - the same gallery workflow the pack's (Deno) Multi Image Loader uses. The card order is the contract: position one becomes <Picture 1>, position two becomes <Picture 2>, and so on, exactly the tags H3 expects in the prompt.

Under the hood each image is decoded on its own and kept in an ordered tuple with no resize, crop, pad, or letterbox pass. The node exposes that as two outputs: the opaque ref_images bundle that only the H3 node understands, and an image_list (a list, not a batch) with the same ordered sources for list-aware nodes like (Deno) Local LLM Loader. Preview cards render at each image's own aspect ratio, so mixed orientations stay readable while you arrange them.

One honest caveat from the README: MiniMax H3 may still downscale references internally during its normal ref_image_size processing. The loader preserves your source; the model's own reference-sizing pipeline is a separate step.

Inputs and outputs

The only input is image_paths - a STRING managed by the node UI, so you never type paths. Outputs:

• ref_images (DENO_MINIMAX_H3_REFERENCE_IMAGES) → wire into the H3 Reference to Video node's ref_images socket.
• image_list (IMAGE list) → same ordered sources, for e.g. (Deno) Local LLM Loader's image input.

The hard limit is nine images; validation will refuse more and tell you so.

Install

Part of the Deno Custom Nodes pack. ComfyUI Manager → search "deno custom nodes", or:

cd ComfyUI/custom_nodes
git clone https://github.com/Deno2026/comfyui-deno-custom-nodes.git
cd comfyui-deno-custom-nodes
python -m pip install -r requirements.txt

Then restart ComfyUI. Two things this node assumes: ComfyUI 0.30.0 or newer (that's when the native H3 nodes landed - older versions simply won't have the stock node this wraps), and the H3 model files themselves, loaded by the stock MiniMax H3 loaders in the workflow. No API key, no extra Python dependencies, nothing to download from the node itself.

Where people get burned

Missing or unreadable files are the common one - the node validates paths before execution and tells you to re-add the image via the Upload/Input Folder button, so drag a file that moved and it'll say so. Picking more than nine references trips a hard validation error; trim the list. And if the connected H3 node doesn't have a ref_images input at all, that's a version problem - update ComfyUI to 0.30.0+. The one to plan around: mixing sizes is fine here, but H3's own ref_image_size step can still normalize references, so if you care about exact framing, test with the reference-size setting on the H3 node before you build a whole batch around it.