MiniMax H3 Ref2VA Prompt Agent (OpenAI API)

Ref2VA is MiniMax H3's multi-reference mode: you hand the model up to nine reference images - a character, a product, a scene you want carried over - and it generates video from them. It's the mode you reach for when a prompt alone can't pin down what's in the frame. The catch is that H3 wants its reference prompts written in a specific structure, and that's exactly the kind of thing you shouldn't have to memorize. This node takes your rough text plus your reference images, sends them to an OpenAI-compatible multimodal model, and returns an H3-structured Ref2VA prompt ready to plug into the official H3 Reference to Video node.

Quick reality check on what it is, because the name overpromises: this is not MiniMax's cloud Context-IR endpoint and it runs no video generation. It's a ComfyUI adapter around the OpenAI Agents SDK that uses the official MiniMax H3 skill files (vendored from the MiniMax-AI/MiniMax-H3 repo, including the ref guide specifically for full-reference mode) to teach an LLM how H3 Ref2VA prompts are built. The actual video comes from the official H3 node; this one just writes its homework for it.

How it works

The node reads the h3-prompt-writing skill plus the Ref2VA reference guide, loads the style-skill folders as tools, and sends your prompt with the reference images attached as JPEG data URLs. The default model is gpt-5.4-mini - you're spending a few pennies per call on a cheap model doing a cheap job, which is exactly the right size for this. It labels each image <Picture N> so the LLM can actually refer to the references by position instead of mumbling "the image." The response is parsed for optimized_prompt, selected_skills, and raw_json, and the whole thing costs you one node added before the official H3 node.

The inputs that matter

• prompt - your rough idea. Multiline, plain English is fine; the agent does the structuring.
• length - the frame count (default 124, about 5s at 24fps). Keep it matching your H3 workflow's own length so the rewrite targets the real duration.
• ref_images - the star of the show. It's an autogrow input (ref_image_1, ref_image_2, …), so you can attach anywhere from zero to nine references and the node grows to match - the same pattern the official MiniMax H3 Reference to Video node uses. Connect the same images to both this node and the H3 node, in the same order.
• model / custom_model - dropdown defaulting to gpt-5.4-mini; custom + custom_model for anything else you can reach via OPENAI_BASE_URL.
• reasoning_effort - low/medium/high/xhigh, default medium. Leave it. Prompt rewriting doesn't need a model that thinks out loud; high effort just makes the call slower and pricier.

Wiring and install

optimized_prompt goes into the official MiniMax H3 Reference to Video node's prompt input. Everything else in your H3 workflow - clip, vae, audio_vae, diffusion model, the width/height/length calc - stays untouched.

Install the pack via ComfyUI Manager (search "MiniMax H3") or:

cd ComfyUI/custom_nodes
git clone https://github.com/JerryZRic/comfyui-minimax-h3-context-ir-agent

Then, the step people skip and immediately regret:

pip install -r requirements.txt   # openai-agents, openai, Pillow, numpy
export OPENAI_API_KEY="sk-..."

This needs a recent ComfyUI build with the typed node API and io.Autogrow support - the ref node literally cannot exist on an older build, so if it's missing from your node list, update ComfyUI first, not the pack. Secrets go in env vars or a gitignored config.toml, never the workflow JSON.

Where people get burned

• The autogrow inputs appear empty until you click and attach an image - a blank ref_image_ that's left unconnected is skipped, which is convenient but means an accidentally-disconnected reference quietly changes your shot.
• "OpenAI Agents SDK is not installed" on first run means the requirements weren't installed into ComfyUI's own Python environment.
• Authentication errors usually mean the key and OPENAI_BASE_URL disagree, or the endpoint doesn't support the Responses API - the node defaults to responses, and you switch api_mode to chat_completions only when your provider forces it.
• "Skills directory not found" - the pack expects its bundled skills/ folder, or wherever you point MINIMAX_H3_SKILLS_DIR. Don't move it.

One honest caveat: this is a brand-new pack (v0.1.0) and the multi-reference H3 path is still settling in the community. The approach - an LLM translating your intent into the official prompt guide - is the pattern people keep landing on, but budget a few test runs before you lean on it for a paying shot.