MiniMax H3 FL2VA Prompt Agent (OpenAI API)

MiniMax H3 is genuinely good at following instructions - but only if you write them in the official H3 prompt structure, and that structure is a lot to remember while you're mid-workflow. This node does the translating for you. You type "a cozy rainy café window, two cups, steam rising," it calls an LLM, and hands you back a properly-structured H3 prompt you can feed straight into the official H3 video node. One of those nodes is worth it; this one makes H3's prompt guide a solved problem instead of a lookup table.

First, the important correction: the name is a lie, kind of. This is not MiniMax's cloud Context-IR endpoint, and it doesn't run H3 itself. It's a local ComfyUI adapter that sends your text prompt (plus any frames you connect) to an OpenAI-compatible multimodal model through the OpenAI Agents SDK, and uses the official MiniMax H3 skill files - vendored straight from the MiniMax-AI/MiniMax-H3 repo - to teach that model how H3 prompts are supposed to look. You still need OPENAI_API_KEY set, or nothing happens.

The one trick: mode is inferred from the images

The node officially does FL2VA (first + last frame to video), but it quietly covers all four H3 keyframe modes at once:

• No image connected → T2VA (text to video)
• Only first_frame → I2VA (image to video) - the common case
• Only last_frame → L2VA
• Both → FL2VA

So it's really four nodes in one, and the mode switches just by what you wire in. The images get converted to JPEG data URLs (compressed, detail fixed to auto, and only resized if the longest edge is above 2048px) and sent to the model labeled with their timestamps - the first frame is pinned to 0.00s, the last to (length-1)/24 seconds, so the LLM knows how long the shot it's writing for actually is.

The inputs that matter

• prompt - your rough idea, plain English. Multiline.
• length - the same frame count as your H3 workflow, default 124 (about 5 seconds at 24fps). Connect the same length you feed the H3 node so the rewrite matches the real duration.
• first_frame / last_frame - optional IMAGE inputs; leave empty and you get T2VA.
• model - dropdown defaulting to gpt-5.4-mini; pick custom and fill custom_model to point at anything else via OPENAI_BASE_URL.
• reasoning_effort - low/medium/high/xhigh, default medium. This is the one I'd leave alone: rewriting a prompt doesn't need deep reasoning, and higher effort means slower calls and more tokens for a job a cheap model does fine.

What comes out

Three outputs, and only one you'll usually wire anywhere:

• optimized_prompt → the rewritten H3 prompt. Feed this into the official MiniMax H3 conditioning node's prompt input. That's the whole wiring job.
• selected_skills → JSON list of which H3 skill folders the agent used (it always includes h3-prompt-writing).
• raw_json → the full parsed response, handy for debugging or learning what the model changed.

Style skills (product ads, brand promos, MV subtitles, that whole list) are exposed as tools, not inputs - the agent decides to use them when the prompt calls for it.

Installing and the gotchas

Easiest: ComfyUI Manager, search "MiniMax H3", install, restart. Or:

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

Then install its deps into ComfyUI's Python environment - this one is not zero-setup:

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

You need a recent ComfyUI build with the typed node API. Three things will bite you, in this order:

1. "OpenAI Agents SDK is not installed" - you skipped the pip install -r requirements.txt step. Do that in the same environment ComfyUI runs in.
2. Authentication errors - the key doesn't match the base URL, or you're pointing OPENAI_BASE_URL at a host that doesn't support the Responses API. The node defaults to responses; switch api_mode to chat_completions only if your endpoint genuinely can't do Responses.
3. "skills directory not found" - it looks for ./skills next to the node by default, or wherever MINIMAX_H3_SKILLS_DIR points. Don't move the folder.

Secrets live in env vars or a gitignored config.toml, never in the workflow JSON - so sharing a workflow won't leak your key, which is the right call for a node that phones home with your credential on every run. Final honest note: this is a very new pack (v0.1.0), and while the approach is exactly the "let an LLM translate into the official prompt guide" pattern the community keeps converging on, give the first run a couple of checks before you trust it blind.