CGFlowStudioGUIDES
Back to All Tutorials
Intermediate22 min read

Complete MiniMax-H3 ComfyUI Workflow Guide: T2V, I2V, R2V & Sage Attention Setup

Step-by-step tutorial on running MiniMax-H3 natively in ComfyUI — from loading official template workflows and model directory setup to advanced multi-reference conditioning and Sage Attention acceleration.

By CGFlowStudio
•
2026-08-16

Complete MiniMax-H3 ComfyUI Workflow Guide: T2V, I2V, R2V & Sage Attention Setup

MiniMax-H3 represents one of the most powerful open-weights video generation architectures available. Uniquely designed as a single-pass omni-modal model, H3 generates synchronized 24 FPS video alongside native 32 kHz stereo audio without requiring secondary lip-syncing or audio stitching models.

With official native support integrated directly into ComfyUI (v0.30.0+), running MiniMax-H3 locally is easier than ever. In this step-by-step workflow guide, we cover everything you need to know: loading official template workflows, configuring model weights, setting resolutions correctly, mastering reference tags, writing optimal prompts, and accelerating generation speeds with Sage Attention.

1. Introduction & Prerequisites

Before diving into workflow execution, ensure your local environment satisfies the following baseline setup:

Minimum Requirements

  • ComfyUI Version: v0.30.0 or later (includes native MiniMax-H3 nodes and template integration).
  • VRAM Workstation Setup:
    • 24 GB VRAM (RTX 3090/4090): Recommended for smooth FP8 / INT8 quantized execution.
    • 16 GB VRAM (RTX 4080/3080 16G): Fully supported using GGUF / quantized weights with CPU offloading.
  • Disk Space: At least 35 GB free for diffusion weights, text encoders, and VAE models.
💡
Why Native MiniMax-H3 Nodes Matter: Earlier third-party wrappers required complex manual scripting. ComfyUI's native implementation provides single-click template loading, automatic prompt tag parsing, and seamless VAE audio decoding directly on your canvas.

2. Getting Started – Loading Official Templates

ComfyUI now includes official built-in template workflows for MiniMax-H3. You do not need to construct nodes manually from scratch.

Step-by-Step Template Loading

1 Update ComfyUI to Latest Version

Open your ComfyUI manager or run git pull in your main directory to ensure core nodes (MiniMaxH3ImageToVideo and MiniMaxH3ReferenceToVideo) are present.

2 Open the Template Library

Click the Templates button on the top menu bar (or top-left panel) inside ComfyUI. Navigate to Video → MiniMax H3.

3 Select Your Target Workflow

Choose from one of the three pre-configured templates:

Template 1

Text-to-Video (T2V)

Generates video and synchronized audio purely from text prompts using FL2VA weights.

Template 2

Image-to-Video (I2V)

Conditions generation using initial (first frame) and/or final (last frame) keyframe images.

Template 3

Reference-to-Video (R2V)

Advanced multi-modal mode locking character faces, motion clips, and voice prompts using Ref2VA weights.

(Note: When loading a template for the first time, ComfyUI can automatically download missing model checkpoints via the pop-up prompt, or you can manually place files as outlined below).

3. Model Files & Directory Structure

To ensure all nodes load smoothly, organize your downloaded MiniMax-H3 weights into standard ComfyUI model subdirectories.

📂 Required Model Hierarchy & Directory Map ComfyUI/models/
📂 ComfyUI/models/
📁 diffusion_models/
📄 MiniMax-H3-Base-FL2VA-int8.safetensors (Used for T2V & I2V)
📄 MiniMax-H3-Base-Ref2VA-int8.safetensors (Used for R2V Multi-Reference)
📁 text_encoders/
📄 Qwen3-VL-32B-layer50.safetensors (50th Layer Vision-Language Encoder)
📁 vae/
📄 H3_VisualVAE_f16t4d24.safetensors (Temporal Visual Decoder)
📄 H3_AudioVAE_32k.safetensors (32 kHz Stereo Audio Decoder)

Model Variant Selection Guide

  • FL2VA Weights: Optimized for single/double frame conditioning and text-to-video generation.
  • Ref2VA Weights: Required when conditioning with multiple reference images, video trajectories, or audio stems.
  • Quantized Options: We recommend using the INT8 / NVFP4 / pruned repackaged versions from Comfy-Org/MiniMax-H3 on Hugging Face to reduce VRAM consumption from ~48GB down to 18–24GB.

4. Setting Output Resolution Correctly

MiniMax-H3 relies on a specialized Resolution Selector node (MiniMaxH3ResolutionSelector) to enforce strict latent aspect ratio and spatial grid rules.

⚙️ MiniMaxH3ResolutionSelector Configuration Rules

Aspect Ratio
Select from 16:9, 9:16, 1:1, 4:3, or 3:4. Default is 16:9 widescreen.
Megapixels
Set target pixel density. 1.0 MP corresponds to native ~768p short-side resolution.
Multiple Factor
Must remain set to 32 to align with VisualVAE 32x spatial downsampling.

Resolution Reference Table

Target Aspect Ratio Recommended Resolution Megapixel Setting VRAM & Performance Impact
16:9 Widescreen 1360 x 768 1.0 MP Recommended starting resolution; high motion fidelity.
9:16 Vertical 768 x 1360 1.0 MP Optimal for mobile & social video workflows.
1:1 Square 1024 x 1024 1.0 MP Balanced composition; slightly higher pixel count.
4:3 Standard 1024 x 768 0.8 MP Fast rendering; lower VRAM footprint.

5. Step-by-Step Workflow Walkthroughs

Workflow A: Text-to-Video (T2V) Mode

In T2V mode, MiniMax-H3 generates both temporal frames and audio soundscapes purely from text conditioning.

Pipeline Flow
CLIPTextEncode (Prompt) → MiniMaxH3ImageToVideo → KSampler → Visual & Audio VAE Decode
  1. Load Node: Add the MiniMaxH3ImageToVideo node to your canvas (or load the T2V template).
  2. Select Weights: Ensure MiniMax-H3-Base-FL2VA-int8.safetensors is connected to the model slot.
  3. Configure Frame Count: Set frame duration using the length field. (Note: MiniMax-H3 snaps frame counts to grid increments such as 22, 39, 56, or 73 frames).
  4. Leave Image Inputs Unconnected: Leave first_frame and last_frame inputs empty for pure text generation.
  5. Run Queue: Click Queue Prompt.

Workflow B: Image-to-Video (I2V) & Keyframe Interpolation

I2V mode locks spatial composition using initial and terminal images.

Keyframe Routing Flow
Load Image (Start) →
Load Image (End) →
MiniMaxH3ImageToVideo
[first_frame] & [last_frame]
KSampler → Output Video + Audio
  1. First-Frame Mode: Connect a Load Image node output into the first_frame socket of MiniMaxH3ImageToVideo. This forces the generated video to begin precisely from your reference image.
  2. Last-Frame Mode: Connect an image into last_frame while leaving first_frame empty to generate reverse motion leading up to a climax frame.
  3. First-and-Last Keyframe Interpolation: Connect distinct images into both first_frame and last_frame. MiniMax-H3 will generate smooth temporal transitions and matching audio bridging the two keyframes.

Workflow C: Reference-to-Video (R2V) Multi-Modal Mode

R2V is MiniMax-H3’s flagship production mode, allowing you to guide character identity, background style, camera trajectory, and vocal timbre using up to 12 reference media files.

🏷️ Using Reference Tags in Your Text Prompt

When running R2V mode with the MiniMaxH3ReferenceToVideo node, you must explicitly assign reference tags inside your text prompt to declare how the model should interpret input files:

Image Tags
<Picture 1>, <Picture 2> ...
Assigns character face, outfit, or background style.
Video Tags
<Video 1>, <Video 2> ...
Assigns camera motion, facial expression, or action.
Audio Tags
<Audio 1>, <Audio 2> ...
Assigns character voice timbre or ambient sound effects.

R2V Input Limits & Composition Rules

  • Maximum Total Files: Up to 12 media files.
  • Individual Caps: Up to 9 Reference Images, 3 Video Clips, and 3 Audio Files.
  • Model Checkpoint: Must switch model checkpoint to MiniMax-H3-Base-Ref2VA-int8.safetensors.

6. Prompting Best Practices

MiniMax-H3 generates joint audio and video, meaning your prompt must provide clear instruction for both visual movements and acoustic details.

Prompt Formula Blueprint
[Subject & Identity] + [Camera & Framing] + [Environment & Action] + [AUDIO: Foley, Timbre, SFX]

Good vs. Weak Prompt Comparison

❌ Weak Prompt

"A guy talking on the street with rain."

Lacks camera direction, lighting specs, temporal pacing, and audio details. Results in generic motion and silent or noisy audio.

✅ Strong Prompt

"Medium close-up shot of a detective standing under a neon awning on a rainy city street. Cinematic 35mm lighting, shallow depth of field. He speaks calmly into a phone. AUDIO: Heavy rain pouring on metal, distant traffic hum, deep voice speaking clearly."

Provides explicit shot framing, lighting, subject action, and precise acoustic environment cues.

7. Speeding Up Generation with Sage Attention

Due to the 33B transformer size, standard attention compute can become a bottleneck during sampling. Installing Sage Attention can increase generation speeds by 30% to 50%.

🚀 How to Enable Sage Attention in ComfyUI

  1. Install PyTorch SageAttention Package: Run pip install sageattention inside your ComfyUI python environment.
  2. Add the Patch Node: Install ComfyUI-KJNodes and add the Patch Sage Attention KJ node to your workflow.
  3. Connect Model Line: Pass the model signal through Patch Sage Attention KJ before feeding it into the main KSampler.
Note on Dtype Warnings: When running SageAttention on certain NVIDIA GPUs, you may see a minor terminal warning regarding FP16/BF16 precision fallback. This is normal and does not affect output audio-video quality.

8. Common Troubleshooting & Gotchas

⚠️ Out of Memory (OOM) Errors

Ensure you are loading quantized weights (int8.safetensors) rather than unquantized BF16 weights. Launch ComfyUI with --lowvram or --no-highvram flags if working on 16GB VRAM GPUs.

📏 Resolution Alignment Errors

Always use MiniMaxH3ResolutionSelector with a multiple factor of 32. Custom canvas sizes that are not multiples of 32 will cause VisualVAE shape mismatch crashes.

⏱️ Frame Length Grid Snapping

MiniMax-H3 operates on an internal $17k + 5$ temporal frame latent grid. Setting custom frame counts like 30 frames will automatically snap to the nearest valid grid number (e.g., 39 frames).

9. Conclusion & Next Steps

Native MiniMax-H3 support inside ComfyUI bridges the gap between text prompts and synchronized audio-video production. By utilizing official template workflows, configuring resolution selectors properly, and applying Sage Attention patches, you can run high-fidelity 768p audio-visual generation directly on local hardware.

What to Explore Next

  • Experiment with R2V multi-reference tags to lock character faces across multiple sequential clips.
  • Try combining MiniMax-H3 output clips with ControlNet or spatial upscalers inside ComfyUI.
  • Check out our related tutorials on the ComfyHub Tutorials Directory.