MiniMax H3 ComfyUI 工作流：T2V 与 I2V 完整指南

在 ComfyUI 中执行 MiniMax H3 需要严格遵守空间和时间网格规则，以防止张量形状错误、静默 MP4 导出或模型崩溃。MiniMax H3 通过在单次前向传播中合成 2K 视频和原生同步立体声音频，解决了这些瓶颈问题。

关键要点：MiniMax H3 ComfyUI 工作流

• 原生多模态通道： MiniMax H3 在单个 ComfyUI 扩散通道中直接合成 2K 视频和同步的 32 kHz 立体声音频。
• 硬件门槛： 执行 INT8 量化至少需要 16 GB VRAM，原生 2K 渲染建议 24 GB。
• 空间网格规则： 画布和关键帧分辨率必须严格能被 32 整除，例如 1344×768，以防止空间 VAE 张量形状错误。
• 时间网格公式： 剪辑长度必须符合总帧数 = 17k + 5 的方程（24fps 下为 5、22、39、56、141 帧），以避免潜在截断。
• 速度优化： 支持官方 8 步 Turbo LoRA，在 CFG 锁定为 1.0 的情况下，渲染时间可降低约 60%。

虽然文本到视频（T2V）依赖于纯文本驱动的潜在初始化，但图像到视频（I2V）使用 first_frame、last_frame 或 MiniMaxH3AddGuide 条件节点来锚定运动轨迹。以下部分详细介绍了两种管线的完整环境设置、节点接线图和故障排除协议。

基本前提条件和模型目录结构

将 32B 文本编码器放入 models/checkpoints 而不是 models/text_encoders 会导致 ComfyUI 在图编译期间冻结，或因无用的 KeyError 而失败。大多数设置失败是因为文件放到了错误的子文件夹中，或者用标准 Qwen 权重替换了 MiniMax H3 所需的自定义视觉文本编码器。

系统兼容性要求

在下载模型权重之前，请确认您的安装满足以下基准硬件和环境规格：

• ComfyUI 核心： 版本 v0.30.0 或更高。
• 自定义节点： ComfyUI-MiniMaxH3-Easy 或官方 Comfy-Org 包。
• GPU VRAM： 16 GB（INT8 最低）/ 24 GB（2K 推荐）。
• 软件栈： Python 3.10+，PyTorch 2.4+，CUDA 12.1+。

模型目录放置矩阵

从 Hugging Face 模型仓库下载官方 MiniMax H3 开源模型权重，并将每个文件放入指定的目标子文件夹。

关键安装说明

qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors 文件是一个自定义的 4 位 AWQ 量化视觉文本编码器（Qwen3-VL 架构），专门为 MiniMax H3 提示条件调整而微调。不要用 text_encoders 文件夹中的标准语言转换器替换它，因为通用语言模型缺乏视频潜在生成所需的多模态视觉投影。

构建文本到视频 (T2V) ComfyUI 节点图

在 ComfyUI 中构建干净的文本到视频 (T2V) 节点图需要以严格的线性顺序路由文本嵌入、空间分辨率设置和潜在帧张量。

节点包说明： 本工作流指南中使用的节点名称，例如 MiniMaxH3TextToVideo 和 MiniMaxH3ImageToVideo，引用的是 ComfyUI-MiniMaxH3-Easy 自定义包。如果您使用的是官方 Comfy-Org 核心包，这些操作将拆分为单独的 MiniMaxH3Sampler 和 MiniMaxH3Conditioning 节点。

分步 T2V 节点接线指南

设置 T2V 潜在生成需要在执行采样器通道之前隔离文本条件和空间参数。

1. 文本编码器接线： 将文本提示节点路由到 Qwen3-VL 视觉文本编码器加载器。将输出张量直接传递到 MiniMaxH3TextToVideo 节点的正向提示条件端口。
2. 空间维度计算： 将 ResolutionSelector 的输出值传递到 ImageScaleToTotalPixels。此步骤计算像素分配，同时强制空间维度保持能被 32 整除。
3. 采样器和潜在生成： 将模型权重、正向条件张量和分辨率参数直接路由到 MiniMaxH3TextToVideo，以生成原始视频潜在表示。
4. VAE 解码和视频导出： 将潜在张量通过 minimax_h3_video_vae_fp16 进行解码，然后将渲染的帧批次直接传递到 SaveVideo。

T2V 节点路由矩阵

要构建此图而不出现依赖关系断裂，请遵循下面概述的精确节点端口连接：

MiniMax H3 几乎完全依赖于由 Qwen3-VL 视觉语言模型解析的详细正向提示，这意味着传统的负向条件节点会增加不必要的计算负载，而不会提高输出质量。将 SaveVideo 直接连接到视频 VAE 解码节点可确保以 24fps 正确渲染 MP4，而不会丢失尾部帧。

构建图像到视频 (I2V) 和首/尾帧工作流

尝试让静态肖像动画化或桥接两个关键帧，通常会导致剧烈的主题扭曲或立即的张量形状崩溃，尤其是当起始和结束图像尺寸相差几个像素时。将标准文本管线转换为图像到视频 (I2V) 工作流需要更换基础采样器节点，并在初始帧和最终帧之间建立精确的图像条件管线。

关键帧插值和节点配置

要从 T2V 过渡到首尾帧 (FL2V) 视频生成，请将 MiniMaxH3TextToVideo 替换为 MiniMaxH3ImageToVideo。此节点公开了专用的输入端口 first_frame 和 last_frame，允许您定义起始状态、结束状态或完整的变形过渡。

1. 加载图像节点： 在画布上放置两个 LoadImage 节点，以保存初始和目标关键帧。
2. 维度匹配： 通过 GetImageSize 路由图像输出，以提取原始宽度和高度尺寸。这可以防止在张量进入采样器之前出现空间网格不匹配。
3. 张量条件： 将处理后的像素张量连接到 first_frame 进行标准单图像动画，或同时填充 first_frame 和 last_frame 以执行关键帧插值。

I2V 和 FL2V 节点连接矩阵

MiniMax H3 强制要求关键帧输入之间的维度严格一致。两个关键帧必须匹配精确的空间分辨率。如果 first_frame 和 last_frame 尺寸不同，采样将在潜在初始化期间停止。通过同一个缩放节点路由两个图像，以确保相同的像素尺寸。

使用 MiniMaxH3AddGuide 的高级参考引导

标准的图像到视频图仅控制第一帧和最后一帧，中间运动未锚定。MiniMaxH3AddGuide 节点通过将参考图像、多帧图像批次或音频轨道锚定在生成时间线上的任何特定 frame_idx 来解决此问题。

MiniMaxH3AddGuide 的核心功能

如何链接锚节点以生成参考视频

链接多个 MiniMaxH3AddGuide 节点可以实现完整的参考视频生成 (R2V)：

1. 主要角色锚点： 将正向条件连接到 MiniMaxH3AddGuide，frame_idx 设置为 0，以在开始时锁定角色身份。
2. 中间序列运动关键帧： 链接第二个 MiniMaxH3AddGuide 节点，在 frame_idx 60 处提供关键帧图像，以强制角色在场景中间达到特定姿势。
3. 音频耦合： 将目标音轨连接到音频输入端口，并传递您的 audio_vae，以直接在该时间线偏移处同步声音。

链接这些条件引导可以保持时间稳定性，而无需强制扩散采样器重新初始化潜在表示。

通过双 VAE 路由集成同步原生音频

创作者通常花费数小时在视频编辑软件中手动对齐外部语音轨道，但最终仍面临不自然的唇形漂移或环境噪音不匹配的问题。MiniMax H3 通过依赖真正的多模态生成，在单次前向传播中合成视频帧和 32 kHz 立体声，从而消除了后期处理音频对齐。

单通道流的架构

与将不同的文本转语音模型链接到视频渲染后的传统管线不同，MiniMax H3 将文本、图像和时间线索处理到统一的潜在空间中。在去噪阶段，SamplerCustomAdvanced 输出包含视觉和声学特征图的复合潜在有效载荷。这种联合合成保证了与屏幕动作精确对齐的对话同步和有机的音效生成。

双 VAE 解码和节点配置

要将原始潜在表示转换为可播放的媒体，图在 MP4 多路复用之前将输出分为两个独立的解码路径。

技术节点设置

1. 加载双 VAE：在画布上添加两个不同的 VAELoader 节点。将第一个指向 minimax_h3_video_vae_fp16.safetensors，第二个指向 minimax_h3_audio_vae_fp32.safetensors。
2. 执行双 VAE 解码：将采样器的视觉潜在输出路由到 VAEDecode，将音频潜在块路由到 VAEDecodeAudio。保持 minimax_h3_audio_vae_fp32 为 FP32 精度可防止背景乐中的削波伪影和频率失真。
3. 通过 SaveVideo 多路复用：将解码后的图像张量和未压缩的音频波形输入 CreateVideo 或直接输入 SaveVideo。该节点处理最终容器打包，写入带有嵌入式立体声音频的 24 fps MP4 文件。

这种原生双流设置可在 ComfyUI 内直接实现相位精确的音频执行，无需外部唇形同步插件。

分辨率数学、宽高比约束和帧网格对齐

在 ComfyUI 中输入标准 1920x1080 分辨率或将剪辑长度设置为 60 帧，将立即导致渲染队列因张量形状错误而崩溃，或留下严重扭曲的边缘接缝。MiniMax H3 对空间维度和剪辑持续时间强制执行严格的数学边界，因为其 3D VAE 架构在特定空间块和时间步长上压缩视频潜在表示。

空间维度和宽高比预设

空间 VAE 将输入下采样 32 倍。如果目标宽度或高度不是严格的 32 的倍数，扩散采样器将在边界张量分配期间失败。该模型以 768px 原生短边为目标，在视觉保真度和目标百万像素预算之间取得平衡。

使用非标准像素尺寸会强制 VAE 填充或拉伸特征图，从而降低精细纹理细节。

17k + 5 帧网格规则

时间维度对齐遵循同样严格的公式。为了保持在 MiniMax H3 视频长度限制 内，该架构以 17 帧潜在块处理视频序列，并带有 5 帧尾部初始化。为避免时间截断或静默 VAE 解码崩溃，每次渲染必须满足 17k + 5 帧网格方程，其中 k 代表整数步长计数器。

在标准 24fps 帧率下，此数学公式决定了精确的持续时间：

• k = 0 (5 帧): ~0.21 秒（微动作或静态爆发）
• k = 1 (22 帧): ~0.91 秒（快速动作片段）
• k = 3 (56 帧): ~2.33 秒（短镜头序列）
• k = 8 (141 帧): ~5.87 秒（完整标准剪辑限制）

将目标计数设置为 60 会强制 ComfyUI 丢弃 4 帧至 56 帧（k=3），在采样期间浪费 VRAM 计算。在排队生成批次之前，始终将节点参数对齐到精确的 17k + 5 步长边界。

速度优化：启用 8 步 Turbo LoRA 执行

在消费级 GPU 上，等待单个 6 秒预览视频渲染超过六分钟，使得快速提示迭代几乎不可能。标准采样需要 20 到 30 步，在调整运动线索、测试摄像机移动或评估关键帧过渡时造成了严重的操作瓶颈。

集成蒸馏权重

集成官方的 minimax_h3_fl2v_turbo_8step_v1.0_comfyui_bf16 权重文件可将采样次数减少到 8 步推理 工作流。此蒸馏过程实现了显著的生成速度优化，而不会损害整体视觉连贯性。

要在 ComfyUI 中配置此蒸馏设置：

1. 放置模型权重：将 minimax_h3_fl2v_turbo_8step_v1.0_comfyui_bf16.safetensors 移动到 ComfyUI/models/loras/ 目录中。
2. 连接 LoraLoader 节点：在将主扩散模型张量送入采样器之前，先通过 LoraLoader 节点路由它。将 turbo_model_strength 设置为 1.0。
3. 调整步数：将 MiniMaxH3Sampler 节点中的 steps 参数从标准的 20 降低到正好 8。
4. 锁定 CFG 缩放：将无分类器引导缩放参数强制设置为 1.0，以避免过饱和。

性能基准：标准与 Turbo 执行

当运行 minimax_h3_fl2v_turbo_8step 时，将 CFG 设置为高于 1.0 会强制进行不必要的双重条件传递，导致颜色严重烧焦、对比度过度曝光以及高运动帧上的空间撕裂。激活 turbo_mode 并固定 Turbo LoRA 强度为 1.0，允许创作者在投入完整的 20 步生产渲染之前，在不到三分钟内验证复杂的摄像机运动。

解决常见的 ComfyUI MiniMax H3 图错误

MiniMax H3 图中的大多数操作失败源于轻微的张量对齐不匹配、未连接的音频解码器或在模型加载期间 GPU 内存瓶颈。

诊断指南与快速修复

1. CUDA 内存不足 (OOM)

   1. 主要原因： 在 16GB VRAM GPU 上同时加载 32B 文本编码器和 int8 扩散权重，且未启用内存卸载。
   2. 分步修复： 在 ComfyUI 启动脚本中添加 --lowvram 或 --medvram 标志。对于 GPU 内存紧张的设置，可考虑在 ComfyUI 中使用 GGUF 量化运行 MiniMax H3 以降低基准内存需求。确保 qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors 严格放置在 models/text_encoders/ 中，允许在文本解析和采样通道之间进行 VRAM 卸载。

2. 形状不匹配错误

   1. 主要原因： 自定义宽度/高度值或输入关键帧图像违反了所需的 32 像素空间可整除性网格。
   2. 分步修复： 在采样器之前插入 ResolutionSelector 或 ImageScaleToTotalPixels 节点，以强制所有画布和图像尺寸对齐到最近的 32 的倍数。

3. 导出中缺少音频轨道

   1. 主要原因： 音频 VAE 路径未连接或在图执行期间被绕过。
   2. 分步修复： 将 minimax_h3_audio_vae_fp32 连接到 VAEDecodeAudio 节点，然后将解码后的音频潜在表示与视频流一起传入 SaveVideo 节点的音频端口。

4. GetImageSize 节点失败

   1. 主要原因： 关键帧宽高比不匹配，或输入到 I2V 采样器的多帧图像批次无效。
   2. 分步修复： 通过统一的 ImageScaleToTotalPixels 节点运行初始和最终图像，以在潜在初始化之前将关键帧锁定为相同尺寸。

5. ComfyUI 管理器缺少节点警告

   1. 主要原因： 所需的 MiniMax H3 自定义节点包未索引或本地环境中缺失。
   2. 分步修复： 打开 ComfyUI 管理器，选择安装缺失的自定义节点，搜索 ComfyUI-MiniMaxH3-Easy，点击安装，然后重启 ComfyUI。

解决内存下降和节点注册表冲突

许多教程忽略了 ComfyUI 如何在连续生成中管理 VRAM 分配。如果在第二次或第三次渲染尝试时突然出现 CUDA 内存不足错误，尽管初始通道成功，则 ComfyUI 已将文本编码器保留在 VRAM 中。在启动脚本中设置显式卸载标志可在采样器步骤之间释放已分配的内存。

打开社区 JSON 文件时，ComfyUI 管理器缺少节点警告通常表示节点注册表过时。直接安装 ComfyUI-MiniMaxH3-Easy 可修复这些缺失的依赖项。对于 I2V 管线，解决 GetImageSize 失败或形状不匹配错误需要确保初始和最终关键帧图像都匹配目标像素边界。