MiniMax H3 Reference to Video

MiniMax H3's whole claim to fame is that it's omni-modal: it treats text, image, video, and audio as one input context and generates video with synced native audio - the thing that used to be Veo's exclusive party trick. Reference to Video is the node that puts all of that on your canvas at once. You feed it up to 9 reference images, up to 3 reference videos, up to 3 audio clips, and a prompt that tells the model which reference you mean when, and it returns a single conditioned clip. This is the "do everything" node of the pack, and for most people it's the reason to install the whole thing.

How it works

The reference inputs are autogrow - click the plus to add more slots up to the per-type caps. On execute the node uploads every image, video, and audio to /v1/files/upload (getting mm_file://{file_id} refs back), then builds one content array for /v2/video_generation where your text prompt comes first and the references follow in the order you attached them. Then the usual poll-and-download, returning a VIDEO.

The key to making it work is referencing by name in the prompt. The tooltip spells out the scheme: Image 1, Image 2, ... Video 1, Audio 1, with numbering per-type and in input order. So a prompt like "Video 1 shows her running toward the door; Image 1 is the building; keep Audio 1 as the ambience" is how you tell the model which reference does what. Get the numbering wrong and the model has no idea which input you meant.

Before anything is sent, the node runs real validation, and this is where most people first hit the limits:

• At least one reference image or video is required. Audio alone is rejected - the tooltip says it and the code enforces it.
• Reference videos must be 23.976–60 FPS, each at least 2 seconds, and the total across all of them must stay under 15 seconds.
• Reference audio follows the same 2-second minimum and 15-second total.
• Images get the same 256×256 minimum and 2:5–5:2 aspect check as the frame nodes.

These aren't the pack's rules, they're the API's - the node is just enforcing them locally so you fail fast instead of paying for a rejected job.

The inputs that matter

• prompt - required, and it's the director's script. Reference images/videos/audio by per-type name.
• reference_images - up to 9 IMAGEs (Image 1..Image 9).
• reference_videos - up to 3 VIDEOs (Video 1..Video 3).
• reference_audios - up to 3 AUDIOs (Audio 1..Audio 3).
• ratio - unlike text-to-video, this node defaults to adaptive and offers the full list (16:9, 4:3, 1:1, 3:4, 9:16, 21:9). Adaptive lets the references set the shape.
• resolution (768P/2K), duration (4–15s), watermark - same as the rest of the pack. And yes, seed is accepted but not sent; ignore it.

Install

Same pack, same steps:

cd ComfyUI/custom_nodes
git clone https://github.com/meta-sota/ComfyUI-MiniMaxH3-API.git
cd ComfyUI-MiniMaxH3-API
pip install -r requirements.txt

Pip dependency is just aiohttp; the real need is a modern ComfyUI (author tests 0.30.0) because this is a V3 native-API pack. No model downloads, no VRAM. Wire the Key node's MINIMAX_H3_KEY output into key.

Common issues

• "At least one reference image or video is required." - you tried audio-only, which the API doesn't allow.
• "Reference video N is X FPS. Supported range is 23.976-60 FPS." - your input video is in an unsupported frame rate. Remux it (ffmpeg -r 30 is the usual fix) before wiring it in.
• "Total reference video duration is ... Maximum is 15 seconds." - trim your clips; the budget is shared across all videos.
• Upload failures - each file is uploaded separately, so a single oversized or corrupt reference fails the whole run. Fix the offending file and re-queue.