ComfyUI-MiniMaxH3 Introduction
ComfyUI-MiniMaxH3 adds custom nodes for creating video and audio together with MiniMax H3 in ComfyUI. You can build a workflow from a text prompt, guide it with images or other media, organize a sequence of shots in a storyboard, and turn the generated result into video frames (IMAGE) and sound (AUDIO).
The extension brings the main stages of that process into a node graph: preparing a prompt and references, loading the required models, generating the result, and decoding it for output. It also offers controls intended to help when model memory is limited, plus optional prompt refiners that can polish storyboard instructions.
How ComfyUI-MiniMaxH3 Works
Think of a workflow as a production line. One set of nodes describes the scene; another loads the models; a sampler creates the video-and-audio result; and a decoder turns that result into frames and sound you can use elsewhere in ComfyUI.
- Describe the scene. Use
MiniMax H3 Simple Promptfor a straightforward prompt, orMiniMax H3 Storyboardto describe multiple shots, subjects, dialogue, and background music. - Add guidance when needed. You can provide first-frame or last-frame constraints, or package image, video, and audio references for a reference-based workflow.
- Prepare and generate.
MiniMax H3 Conditioningturns the prompt and supported references into the inputs needed byMiniMax H3 KSampler. The sampler generates a joint audio-video latent: an intermediate representation that still needs decoding. - Decode the result.
MiniMax H3 Decode AVconverts that latent intoIMAGEandAUDIOoutputs.
For example, a simple text-led workflow follows this path:
Simple Prompt → Conditioning → KSampler → Decode AV → output
A storyboard can take the place of the simple prompt when you need a planned sequence of shots. A Refiner can sit between the storyboard and Conditioning to produce a polished prompt; its result appears in a built-in preview panel.
ComfyUI-MiniMaxH3 Features
Prompts, storyboards, and references
| Node | What it helps you do |
|---|---|
MiniMax H3 Simple Prompt | Build a prompt payload for text-to-video-and-audio (T2VA), image-guided (I2VA), first/last-frame-guided (FL2VA), or last-frame-guided (L2VA) work. |
MiniMax H3 Storyboard | Plan multiple shots in a structured editor, including subjects, dialogue, and a background-music description. |
MiniMax H3 FL Constraint | Guide the beginning and/or end of a generation with a first or last frame. Connect it to Conditioning when using those constraints. |
MiniMax H3 PackageData | Combine image, video, and audio references loaded through the interface or supplied externally. |
MiniMax H3 VideoBatch | Package up to three independent video references. |
MiniMax H3 Conditioning | Prepare positive and negative conditioning and the audio-video latent. Its width and height settings define the output latent resolution. |
Choose the appropriate guidance path: MiniMax H3 FL Constraint and MiniMax H3 PackageData cannot be used in the same Conditioning node.
Subjects, dialogue, and music
In the Storyboard subject column, you can define a recurring character once and then refer to that character by name in shot prompts. For example:
Name: Alice
Definition: a woman in the appearance of <Picture 1>.
Outside dialogue tags, the extension converts defined subject names into the subject labels used by the prompt. Text inside <d>...</d> is protected, so spoken words are not changed. Speaker IDs such as (S1) and (S2) follow vocal order. Refiner models normally write these IDs, but you can also enter them yourself:
[Shot 1] <Subject 2> (S1) says: <d>[English] Hi Bob.</d>
[Shot 2] <Subject 1> (S2) says: <d>[English] Hello Alice.</d>
[Shot 3] Alice (S1) says: <d>[English] Let's go.</d>
Use the Storyboard’s music_style field for background music that the audience hears, rather than sound occurring within the scene. A useful description might specify an instrument, rhythm, and how the music changes: “solo piano, slow and sparse, gradually fading.” Keep dialogue, singing, and physical sound effects out of this field. Leaving it empty produces N/A.
Prompt refinement
MiniMax H3 Context IR Refinercalls the official MiniMax H3 Context IR API.MiniMax H3 OpenAI-Compatible Refinercalls a user-configured OpenAI-compatible chat API.
Both show the polished prompt in a preview panel, allowing you to inspect it before generation. The official Refiner reads its API key from the IR_KEY environment variable; the OpenAI-compatible Refiner reads it from an environment variable you select. API keys are not stored in workflow JSON.
Model loading and generation controls
| Node | Purpose |
|---|---|
MiniMax H3 Model Loader (Streaming) | Loads the main generation model lazily and supports BlockSwap. |
MiniMax H3 VAE Loader | References the video and audio VAE weights needed for decoding. |
MiniMax H3 Text Encoder Loader | Loads the included Qwen3-VL-32B text encoder. |
MiniMax H3 LoRA Loader | Loads complete pruned LoRA files in the supported format. |
MiniMax H3 Attention Config | Selects an attention backend, with automatic fallback. |
MiniMax H3 KSampler | Runs the H3 audio-video sampling step through ComfyUI k-diffusion. |
MiniMax H3 TeaCache Args | Configures TeaCache block skipping. |
MiniMax H3 BlockSwap Args | Configures BlockSwap, prefetch, pinning, and data type for memory-conscious loading. |
MiniMax H3 Decode AV | Produces IMAGE and AUDIO from the generated latent. |
MiniMax H3 Unload All | Frees cached models, VAEs, and encoders when you are finished with them. |
BlockSwap is designed for low-VRAM use, with a CPU home pool and optional disk prefetch. These settings affect how model data is managed during generation; they are useful when available graphics memory is a constraint. The extension also includes an AdaLN cache that can prepare modulations before sampling. The dpm_adaptive sampler instead uses the eager AdaLN path because its schedule is determined during the run.
ComfyUI-MiniMaxH3 Models
The extension uses several model components with different jobs. They are not interchangeable presets for visual style:
| Component | Role | Standard ComfyUI model folder |
|---|---|---|
| DiT / Ref2VA checkpoint | The main generation weights; use the checkpoint appropriate to your workflow. | ComfyUI/models/diffusion_models/ |
| Qwen3-VL text encoder | Prepares text for the generation workflow. | ComfyUI/models/text_encoders/ |
| Video VAE and audio VAE | Decode the generated latent into video frames and sound. | ComfyUI/models/vae/ |
The loader detects these supported DiT weight formats from checkpoint metadata: bf16, fp16, fp8, int8, nvfp4, and convrot. These names describe how weights are stored, not different creative themes or prompt styles.
For LoRA use, MiniMax H3 LoRA Loader accepts complete pruned MiniMax-H3 LoRA files generated by the MiniMax-H3 Pruned LoRA Adapter tool. The complete file includes backbone LoRA keys and the required AdaLN data. AdaLN replacement happens during model loading, so a separate h3_silu_temb_grid.safetensors file is not required. Original 2688-dimensional AdaLN Turbo LoRAs are not supported directly on pruned models; they must first be baked into a complete pruned LoRA.
Troubleshooting ComfyUI-MiniMaxH3
A model does not appear in its loader.
- Check which component the node expects: the main checkpoint, text encoder, or video/audio VAE.
- Confirm the file is in its corresponding standard ComfyUI model folder listed above.
- Confirm you have selected the intended file in the relevant loader.
Conditioning rejects the guidance inputs.
- Check whether both
MiniMax H3 FL ConstraintandMiniMax H3 PackageDatafeed the same Conditioning node. - Use only one of those two guidance paths for that Conditioning node.
- Reconnect the chosen guidance and run the workflow again.
KSampler reports a missing latent.
- Connect the latent prepared by
MiniMax H3 ConditioningtoMiniMax H3 KSampler. - Check that the connection reaches the KSampler’s
latentinput. Although that socket is optional in the node schema for display purposes, sampling requires a latent.
A Refiner cannot access its API.
- For
MiniMax H3 Context IR Refiner, check that the API key is available throughIR_KEY. - For
MiniMax H3 OpenAI-Compatible Refiner, check that the selected environment variable contains the intended key. - Inspect the Refiner’s built-in prompt preview to see whether it returned a polished prompt. Keys are not stored in the workflow JSON.
A LoRA does not load on a pruned model.
- Check that it is a complete pruned LoRA in the format expected by
MiniMax H3 LoRA Loader. - If it is an original 2688-dimensional AdaLN Turbo LoRA, bake it into a complete pruned LoRA using the linked adapter tool before loading it.
Frequently asked questions
Can I guide both the first and last frame?
Yes. MiniMax H3 FL Constraint supports first-frame and/or last-frame constraints. Connect it to Conditioning.
Can I use multiple video references?
MiniMax H3 VideoBatch packs up to three independent video references.
Why did a character’s name become a subject label?
Defined Storyboard subject names are converted outside <d>...</d> so the prompt uses standard subject labels. Spoken dialogue inside those tags is left untouched.
Where should I describe singing or sound effects?
Do not place them in music_style; that field is for background music heard only by the audience. Leave it blank when you do not need that music description.
How do I release models after a session?
Use MiniMax H3 Unload All to free the extension’s cached models, VAEs, and encoders.
Learn More about ComfyUI-MiniMaxH3
- MiniMax-H3 Pruned LoRA Adapter: the tool referenced by the author for producing complete pruned LoRA files accepted by this extension.
