JR MiniMax H3 Prompt Optimizer (OpenAI Compatible)

MiniMax H3 prompts are not freeform. The model expects a fairly rigid structure - fields, shots, timestamps, dialogue, reference labels - and if you just paste a sentence in, you're leaving most of the model's omni-modal capability on the table. The JR H3 Prompt Optimizer is a local preprocessor that turns a loose prompt into a properly-formed H3 prompt, and the key architectural decision is this: the LLM only produces semantic JSON, and the final H3 structure is generated deterministically in Python against a fixed spec. The model gets a schema to fill in; it doesn't get to free-style your formatting.

That spec matters enough that the pack pins it: it follows the Prompt Writing rules from a specific MiniMax-H3 commit (8d8824ef…), so the output matches what the model expects. It's a local preprocessor, not MiniMax's hosted H3-Context-IR - you point it at any OpenAI-compatible /v1/chat/completions service, from a local vLLM on http://127.0.0.1:10000 to a hosted endpoint with a key. That means no upload of your images to a vendor unless you choose to point it somewhere that reads them; the node downsizes reference images to image_send_size for the vision call.

The mode system is the part that matters

h3_input_mode (default Auto) picks the generation mode from what you've connected, and the README's table is the truth here:

• Any reference IMAGE (or valid reference labels in reference_instructions) → Ref2VA
• Only first_frame → I2VA
• first_frame + last_frame → FL2VA
• Only last_frame → L2VA
• Nothing → T2VA

Explicit modes refuse conflicting inputs instead of silently switching, which is the right kind of stubborn. Reference slots ref_image_1 through ref_image_9 each accept an IMAGE batch, and there's a pip input for the Director chain - when a JR_H3_DIRECTOR_PIPE is connected, its timeline/registry is authoritative and the legacy first_frame/last_frame widgets will error rather than silently override.

The optimizer is a "closed-world faithful" rewriter: your directions, timing, explicit requirements, and what's directly visible in reference images are the complete truth source. Profiles (Standard, Cinematic Drama, Action, Character Consistency) can change emphasis but can't invent relationships, motives, or events, and unspecified content must be omitted rather than guessed with "perhaps" filler.

The outputs

optimized_prompt (the formatted H3 text you wire into conditioning or the cache router), original_prompt (echo), status (Success: model=… mode=… repaired=0/1, or a Fallback: reason), and a derived pip in Director mode. If the LLM's JSON fails schema validation it gets one structural repair pass at temperature=0.1; if it still fails, fail_mode decides: Return Original (safe default, keeps your workflow alive) or Stop Workflow (raises so you notice). Dialogue text is protected verbatim - it's not paraphrased.

Install & run

cd ComfyUI/custom_nodes
git clone https://github.com/Goldlionren/ComfyUI_JR_MiniMaxH3Node
<your-comfyui-python> -m pip install -r ComfyUI_JR_MiniMaxH3Node/requirements.txt

or search ComfyUI_JR_MiniMaxH3Node in ComfyUI Manager. There's no bundled LLM - you bring the OpenAI-compatible endpoint. api_base_url accepts a bare root, /v1, /v1/models, or the full /v1/chat/completions path; leave model empty and it queries /v1/models at execution time.

Troubleshooting

• Fallback: status with Return Original means the endpoint is unreachable or the schema repair failed. Check the URL first - a local server that isn't listening at 127.0.0.1:10000 is the #1 cause.
• Weak structure even on "Success". Different models give different semantic quality; the node guarantees the format, not the model's judgment. Try a stronger model or lower temperature.
• Mode feels wrong. Verify what's actually connected to the reference/first/last-frame inputs - Auto mode is a pure function of those connections.