ComfyUI-MiniMax-H3-Guide
Guided MiniMax H3 prompt preparation node for ComfyUI
Nodes (29)
The legacy picture/video reference for Qwen's prompt-writing context
The 50–63 layer tail that unlocks Qwen3-VL for the H3 conditioning CLIP
Recombine video and audio latents frame-locked to 40 Hz
Unpack an H3 AV latent without LTX assumptions
Edit the enhanced prompt by hand without breaking the H3 structure
The handoff node that finally talks to MiniMax's own H3 nodes
Give H3 a voice, a beat, or a sound texture without mashing them together
Swap one actor for another inside an existing video
Attaching dialogue to a shot
H3 foley without a reference stream
Tell MiniMax what a picture is for — and what it should not copy
Every H3 video starts with a 17k+5 frame count — this node picks it
Let Qwen add production detail without touching your structure
The H3 compiler that turns your node graph into a real MiniMax prompt
A/B test a prompt override without rewiring your graph
The last gate before your prompt hits MiniMax
Building the H3 timeline one cut at a time
Pin one exact image to one exact shot
Borrow a clip's motion without borrowing its face
The multi-role reference node
Tell MiniMax H3 what your reference video is for
Let a Qwen CLIP write your H3 prompt — without letting it wreck the format
A form that writes MiniMax H3's nightmare prompt for you
A reusable media library for MiniMax H3, gallery included
Route saved audio into H3's native ref_audio socket, with the right intent
Bridge a saved reference into the H3 chain
Build H3's shot timeline without hand-typing timestamps
The three-output node that keeps your H3 graph from forming a loop
The fine-grained role node for H3 references
ComfyUI MiniMax H3 Guide
A dependency-free ComfyUI node pack for building MiniMax H3 prompts from explicit references, subjects, and shots. It compiles those choices into valid H3 prose and routes the media to ComfyUI's native H3 nodes.
- Typed Plan v2 workflow instead of one large prompt form
- Explicit identity, keyframe, motion, edit-source, voice, and soundtrack roles
- Deterministic labels, timing, validation, and native media routing
- Optional Qwen enhancement with compiler-owned structure kept locked
- Reusable image/audio Reference Sheets and a locked-picture Foley mode
- H3-native AV split/repack with frame-locked audio length
Install
cd ComfyUI/custom_nodes
git clone https://github.com/ethanfel/ComfyUI-MiniMax-H3-Guide
Restart ComfyUI, then look under MiniMax H3 → Plan v2. The pack has no additional Python dependencies.
This release requires a ComfyUI build with native MiniMax H3 support. Update ComfyUI if MiniMax H3 Image to Video, MiniMax H3 Reference to Video, or the MiniMax tokenizer is missing.
Start here
Project Setup
→ optional Image / Video / Audio References
→ one Shot per real cut
→ Prompt Merge
→ Apply Reference Plan
→ sampler
- Project Setup selects the output size and native frame count.
- Reference nodes declare what each file means. The compiler assigns H3 labels and routes automatically.
- Shot nodes define the timeline. Attach keyframes, motion, and dialogue to the Shot that uses them.
- Prompt Merge validates and compiles the plan.
- Apply Reference Plan hands the matching prompt, media, and AV latent to ComfyUI's native H3 implementation.
For the complete node-by-node workflow, see the Plan v2 guide.
Pick roles by intent
| Intent | Use | | --- | --- | | Exact opening or ending composition | Image Reference as an endpoint | | Preserve identity, wardrobe, object, scene, or style | Image Reference as reusable content | | Transfer pose, action, or body mechanics | Video Reference + Attach Motion | | Modify an existing video | Video Reference as an edit source | | Continue an existing video | Video Reference as a continuation source | | Keep or copy source audio | Paired Audio Reference with continuity/copy role | | Borrow voice, beat, music style, or sound texture | Audio Reference with the matching guidance role |
The same file type can take different routes. Its intended job—not its extension—decides the H3 mode.
Example workflows
Examples are available in example_workflows/ and
ComfyUI's workflow template browser.
| Workflow | Status | Purpose | | --- | --- | --- | | Animate Keyframe with Motion Reference | Ready | Retarget motion onto a supplied opening keyframe | | Prompt Builder App | WIP | Prompt-only Plan v2 interface | | Identity and Voice | WIP | Identity, voice, dialogue, and Ref2VA generation | | First and Last Frames | WIP | Exact endpoint composition | | Five Shot Keyframe Composition | WIP | Per-shot keyframes and motion transfer | | Character Replacement | WIP | Replace one performer in an edit-source video | | Video Extension with Audio Continuity | WIP | Character transfer plus continuation | | Video to Audio Foley | WIP | Locked picture track with generated audio | | Foley with Sound Reference | WIP | Foley guided by a sound texture | | Foley with Multiple Sound and Voice References | WIP | Multi-reference Foley and dialogue |
The ready motion-reference workflow is the reference implementation. WIP templates expose their intended graph but still need task-specific media and default refinement.
Limits worth knowing
| Constraint | H3 limit |
| --- | --- |
| Output | 4–15 seconds on the native 17k+5 frame grid at 24 FPS |
| Images | 9 |
| Videos | 3 |
| Audio clips | 3 |
| Mixed reference files | 12 total |
| Each reference video or audio clip | 2–15 seconds |
| Cumulative video references | 15 seconds |
| Cumulative audio references | 15 seconds |
The 362-frame endpoint plays for 15.083 seconds. One complete-copy or continuity soundtrack paired with a matching 362-frame video may share that padded boundary; it does not increase the general audio limit.
Guides
- Plan v2 workflow and node reference
- Video-to-audio Foley
- Qwen enhancement and prompt review
- Persistent Reference Sheets
- H3 AV latent split and frame-locked repack
- Preparing reference media
- Migrating legacy workflows
- Audit and compatibility decisions
Legacy nodes remain registered so existing workflows load. New projects should use Plan v2.
Development
pytest -q
Credits
The interaction direction was inspired by ComfyUI-MiniMaxH3-Easy, used under its MIT license. This project retains an independent Plan v2 data model, validator, router, and compiler.
The H3 AV timing nodes were cross-checked against ComfyUI's native H3 grid formulas and the independent findings in ComfyUI-MMH3Tools.
Prompt structure follows MiniMax's official base guide, reference guide, and model card.
License
GNU General Public License version 3 only (GPL-3.0-only).