# ComfyUI-MiniMaxH3 ComfyUI custom nodes for MiniMax H3 joint video and audio generation. The package includes streaming model loading, BlockSwap, quantized weight support, a vendored Qwen3-VL-32B text encoder, prompt and storyboard tools, Refiner nodes, an H3 KSampler, decode, and output utilities. ## Installation 1. Copy the repository folder into `ComfyUI/custom_nodes/`. 2. Install dependencies: ```bash pip install -r requirements.txt ``` 3. Restart ComfyUI. ## Model Files Place model files in the standard ComfyUI model folders: | Model | Folder | |---|---| | DiT / Ref2VA checkpoint | `ComfyUI/models/diffusion_models/` | | Qwen3-VL text encoder | `ComfyUI/models/text_encoders/` | | Video VAE and audio VAE | `ComfyUI/models/vae/` | Supported DiT weight formats are detected automatically from checkpoint metadata: bf16, fp16, fp8, int8, nvfp4, and convrot. ## API Keys - `MiniMax H3 Context IR Refiner` reads the API key from the `IR_KEY` environment variable. - `MiniMax H3 OpenAI-Compatible Refiner` reads the API key from a user-selected environment variable. API keys are not stored in workflow JSON. ## Nodes | Node | Purpose | |---|---| | MiniMax H3 Model Loader (Streaming) | Loads the DiT lazily with BlockSwap support | | MiniMax H3 LoRA Loader | Loads complete pruned LoRA files generated by the LoRA tool | | MiniMax H3 VAE Loader | References video and audio VAE weights | | MiniMax H3 Text Encoder Loader | Loads the vendored Qwen3-VL-32B encoder | | MiniMax H3 Attention Config | Selects an attention backend with automatic fallback | | MiniMax H3 Conditioning | Builds positive/negative conditioning and the AV latent | | MiniMax H3 FL Constraint | Provides first-frame and/or last-frame constraints | | MiniMax H3 PackageData | Combines UI-loaded and external image/video/audio references | | MiniMax H3 Storyboard | Structured multi-shot storyboard editor | | MiniMax H3 Simple Prompt | Builds a simple T2VA/I2VA/FL2VA/L2VA prompt payload | | MiniMax H3 VideoBatch | Packs up to three independent video references | | MiniMax H3 Context IR Refiner | Calls the official MiniMax H3 Context IR API | | MiniMax H3 OpenAI-Compatible Refiner | Calls any OpenAI-compatible chat API | | MiniMax H3 KSampler | Runs the H3 packed AV sampler through ComfyUI k-diffusion | | MiniMax H3 TeaCache Args | Configures TeaCache block skipping | | MiniMax H3 BlockSwap Args | Configures BlockSwap, prefetch, pinning, and dtype | | MiniMax H3 Decode AV | Decodes the joint latent into IMAGE and AUDIO | | MiniMax H3 Unload All | Frees cached models, VAEs, and encoders | ## Typical Workflows ### T2VA / FL2VA ```text SimplePrompt -> MiniMax H3 Conditioning -> MiniMax H3 KSampler -> MiniMax H3 Decode AV -> output ``` Connect `MiniMax H3 FL Constraint` to `MiniMax H3 Conditioning` when using first-frame or last-frame constraints. ### Ref2VA ```text PackageData -> MiniMax H3 Conditioning -> MiniMax H3 KSampler MiniMax H3 VAE Loader -> MiniMax H3 Decode AV -> output ``` ### Storyboard and Refiner ```text Storyboard -> Refiner -> MiniMax H3 Conditioning -> MiniMax H3 KSampler -> MiniMax H3 Decode AV -> output ``` Both Refiner nodes display the polished prompt in a built-in preview panel. Polling checks for ComfyUI cancellation between API requests. ## LoRA Tool Generate complete pruned MiniMax-H3 LoRA files with: ```text https://github.com/xiaolibai-sys/MiniMax-H3-Pruned-Lora-Adapter ``` The generated LoRA contains: ```text backbone LoRA keys adaln_t_table blocks.*.adaln_proj.linear.weight/bias final_layer.adaln_proj.linear.weight/bias ``` The `MiniMax H3 LoRA Loader` node accepts this complete pruned LoRA format directly. AdaLN replacement is applied during model loading, so `h3_silu_temb_grid.safetensors` is not required. Original 2688-dim AdaLN Turbo LoRAs are not supported by the node on pruned models; bake them into a complete pruned LoRA first. ## Storyboard Subjects and Dialogue Global Subjects can be defined in the Storyboard subject column: ```text Name: Alice Definition: a woman in the appearance of

MiniMax H3 Storyboard

Inputs (0)

Outputs (1)