H3 Codex Promptor (Trent)

MiniMax H3 doesn't take a paragraph. It takes a document - either the three-field base format (integrated_multimodal_description, overall_soundscape, non_diegetic_music) or the six-section Ref2VA one, which adds subject definitions, a retention analysis and <Picture 1> / <Video 1> / <Audio 1> labels. Get the structure wrong and you're debugging a 33B video model when the real problem was your formatting.

MiniMax publishes an official prompt-writing guide, so Trent's answer is: don't paraphrase it in a system prompt, load the real thing. H3 Codex Promptor sends your brief and reference frames to Codex CLI (the one your ChatGPT subscription covers), gets a prompt written against MiniMax's own skill document, checks it locally, and drops it into an editable box wired to your sampler. No API key, despite the name.

How it works

The node spawns codex app-server --listen stdio:// as a private subprocess in a throwaway temp dir, with OPENAI_API_KEY and CODEX_API_KEY stripped out of the environment. The session is pinned to ChatGPT sign-in, so it bills your subscription and can't quietly fall back to API billing. Shell, web search and multi-agent are disabled - the model gets the skill, your images and a schema, nothing else.

The system prompt is MiniMax's official h3-prompt-writing skill plus your mode's reference guide - downloaded at a pinned commit on first use, SHA-256 verified, cached under ComfyUI/user/default/trentnodes/h3_codex/skills/. Codex returns the body plus an assumptions list; deterministic local checks then run on formatting, shot timing and reference labels. Fail them and the model gets exactly one corrective turn. Whatever comes back is returned as-is with the diagnostics attached - nothing is silently rewritten.

The inputs that matter

creative_brief is the box you fill in. duration_seconds (default 6) must match the clip you'll generate; the official guide is written around 4–15s.

mode on auto reads your wiring: text only → T2VA, first_frame → I2VA, last_frame → L2VA, both → FL2VA, and any of reference_images, video_frames or audio → Ref2VA. Note that last one: wiring audio alone flips you to the six-section Ref2VA format - correct H3 behaviour, but it surprises people who only wanted to declare <Audio 1>. Base modes want exact picture counts (1 for I2VA/L2VA, 2 for FL2VA), and labelling follows first frame, last frame, then reference_images in batch order. Wire H3 in that same order or the prompt describes the wrong picture.

action is generate / refine / locked, and prompt_text is the editable result, saved inside the workflow. refinement is the change request for an existing prompt. video_frames takes a VHS IMAGE batch and sends sampled keyframes (max_frames, default 8, timestamps from fps) - never the video, never its audio. reference_roles, context and dialogue explain what each reference supplies and carry the exact words H3 should speak; source_soundscape, source_music and sound_log are built for H3 Audio Soundscaper's outputs, because this node cannot hear anything.

Outputs

h3_prompt goes into your H3 text input. checkpoint_hint names the shape you need - MiniMax-H3-Base-FL2VA for base modes, MiniMax-H3-Base-Ref2VA for Ref2VA. validation_report holds the diagnostics, frame times, assumptions and skill revision; right-click → Show Codex validation report shows the same. overall_soundscape and non_diegetic_music are split out of the body for workflows that want those as separate text inputs.

Installing it

cd ComfyUI/custom_nodes
git clone https://github.com/TrentHunter82/TrentNodes.git
cd TrentNodes && pip install -r requirements.txt

Or search "Trent Nodes" in ComfyUI Manager. The requirements file is the whole pack's (opencv, matplotlib, psd-tools, timm, transnetv2-pytorch, the API SDKs) - a heavy install for a node gallery.

The real prerequisite isn't pip:

# same environment/user ComfyUI runs as (inside WSL, if that's where ComfyUI lives)
codex login

The CLI must be on ComfyUI's PATH or at ~/.local/bin/codex, otherwise set TRENT_CODEX_BIN. Restart ComfyUI, refresh the browser, and start from example_workflows/H3_Codex_Promptor.json.

Where people get burned

Nothing changed on Run. Locked mode is the default after a successful generate, and locked prompts ignore edits to your brief and references by design. Hit Generate, or use New variation.

A seed variation returned the identical prompt. That's the cache: results are keyed on brief, images, mode, duration, model, effort, skill version and revision, so a new H3 seed spends no Codex usage. Changed your Codex model, or want a fresh draft? Bump revision.

Login expired. Run codex login as the ComfyUI user; a cached codex login status isn't proof.

Generate/Refine buttons do nothing inside a subgraph. They're main-canvas only; set action and press Run. And the first unlocked run needs GitHub once for the skill - after that it's local.

Two things before you invest: your brief, context and sampled frames go to Codex while H3 renders locally, and the H3 Community License excludes the US, EU, UK and South Korea - a fair number of readers aren't licensed to run the local weights at all.