ComfyUI-YCNodes-MiniMax-H3 README

The project's README from github.com/yichengup/ComfyUI-YCNodes-MiniMax-H3. As one markdown file: README.md.

ComfyUI-YCNodes-MiniMax-H3

专为 MiniMax H3 视频模型打造的 ComfyUI 节点包，包含 6 个节点，覆盖二采条件注入、时间分段提示词控制、注意力感受野约束、动态 CFG 调度、低噪细节精修和空间分块采样。

无第三方依赖，仅需 PyTorch。

推荐一个在线一键运行的comfyui平台 中国国内runninghub ---- 国际runninghub 丰富的插件和模型，点开即用

节点总览

节点 分类 功能
MiniMax H3 Image to Video (Tail) conditioning 二采版条件节点，可透传一采 latent 续跑后段采样
H3 Prompt Relay conditioning 时间分段提示词控制，不同时间段只关注对应 prompt
H3 Distance Attention Patcher 注意力 时空高斯感受野遮罩，防止背景同化局部细节
H3 Dynamic CFG Scheduler scheduler 根据去噪阶段动态调整 CFG 引导强度
H3 Sigma Refiner scheduler 低噪区间局部加步，消除运动边缘像素颗粒
H3 Tiled Sampler sampling 分块采样，降显存，基于10S-Comfy-nodes的LTX Tiled Sampler,改造而来

1. MiniMax H3 Image to Video (Tail)（二采条件节点）

原理： 官方 MiniMaxH3ImageToVideo 每次都输出空 AV latent（纯噪声起点），无法用于二采续跑。本节点新增 video_latent 输入：传入一采输出的 latent 时直接透传，并按实际帧数重算关键帧锚点，实现后段采样/高清精修。

二采高清用法： 一采输出 LATENT 接 video_latent，首帧/末帧可选，width/height 自动对齐二采 latent 分辨率。apply_keyframes 设为 disable 可跳过关键帧注入。

参数 类型 默认值 说明
clip CLIP - H3 CLIP 模型
vae VAE - H3 VAE
prompt STRING - 提示词
width INT 1344 二采目标分辨率宽（自动对齐 video_latent）
height INT 768 二采目标分辨率高（自动对齐 video_latent）
length INT 124 帧数，未传入 video_latent 时决定空 latent
first_frame IMAGE 可选 首帧图像
last_frame IMAGE 可选 尾帧图像
video_latent LATENT 可选 一采输出的 latent，传入后透传并重算锚点
apply_keyframes COMBO enable enable / disable，关闭时跳过关键帧注入

2. H3 Prompt Relay（时间分段提示词控制）

原理： H3 使用打包自注意力（text + cond + audio + video 在同一序列），不存在独立 cross-attention。本节点通过对自注意力矩阵中 video query -> text key 路径施加时间惩罚 mask，实现不同时间段只关注对应 prompt 的效果。

用法： 将官方 prompt 原文复制到 local_prompts，在分段处加 | 分隔符。global_prompt（可选）填入全局风格基调，全程对所有帧可见。支持官方图生视频节点（MiniMaxH3ImageToVideo）及多参版本（MiniMaxH3ImageToVideoMultiParams）。

CLIP -> [MiniMaxH3ImageToVideo / MultiParams] -> CONDITIONING ─┐
CLIP ──────────────────────────────────────────────────────────┤
latent ──────────────────────────────────────────────────────> [H3PromptRelay] -> MODEL -> [采样器]
                                                                ↑                   CONDITIONING
                                                                └─── (透传) ─────────┘
参数 类型 默认值 说明
model MODEL - H3 模型
conditioning CONDITIONING - 官方节点输出的 conditioning
clip CLIP - H3 CLIP 模型
latent LATENT - H3 视频 latent
global_prompt STRING 空 全局风格/主题基调，全程对所有帧可见（可选）
local_prompts STRING 空 分段提示词，用 | 分隔
segment_lengths STRING 空 逗号分隔的像素帧数，留空自动均分
epsilon FLOAT 0.001 惩罚衰减参数，越小边界越锐利
patch_ratio FLOAT 1.0 0.0-1.0，打 patch 的 DiT Block 比例。有语音时建议 0.3-0.7

3. H3 Distance Attention Patcher（距离注意力约束）

原理： 针对全景场景下肢体和面部容易被背景同化或扯碎的问题，通过时空高斯感受野遮罩强行约束模型在中前期去噪时的局部注意力，阻断大面积背景对微小细节的特征同化。

参数 类型 默认值 范围 说明
model MODEL - - H3 模型
receptive_field_scale FLOAT 15.0 1.0 ~ 100.0 感受野尺度，越小越局部
temporal_weight FLOAT 2.0 0.1 ~ 10.0 时间轴相对空间轴的距离权重
start_at_sigma FLOAT 4.5 0.0 ~ 20.0 开始约束的 Sigma 阈值
end_at_sigma FLOAT 0.0 0.0 ~ 5.0 结束约束的 Sigma 阈值
num_frames INT 17 1 ~ 256 视频总帧数
original_width INT 864 128 ~ 2048 视频宽度
original_height INT 480 128 ~ 2048 视频高度

4. H3 Dynamic CFG Scheduler（动态 CFG 调度）

原理： 根据去噪阶段动态调整 CFG 引导强度。高 sigma（早期构图）用低 CFG 保大形，低 sigma（后期细节）用高 CFG 提细节。H3 flow matching 默认 CFG=1.0，动态范围很小，微调即可。

接线： 插在 MODEL 和采样器之间。

参数 类型 默认值 范围 说明
model MODEL - - H3 模型
cfg_low FLOAT 0.9 0.5 ~ 2.0 高 sigma 时的 CFG（早期构图）
cfg_high FLOAT 1.1 0.5 ~ 2.0 低 sigma 时的 CFG（后期细节）
start_at_sigma FLOAT 3.0 0.0 ~ 20.0 开始动态调度的 Sigma 阈值
end_at_sigma FLOAT 0.0 0.0 ~ 5.0 结束动态调度的 Sigma 阈值

5. H3 Sigma Refiner（低噪细节精修）

原理： 对低 Sigma 区间进行局部加步——保留原始调度的高噪头部不动，从阈值点起把尾部重采样成更长、更平滑的曲线，让模型在细节收尾阶段多走几步，消除高速运动边缘的马赛克与像素紊乱。

接线： 插在调度器和采样器之间。

BasicScheduler -> (sigmas) -> H3 Sigma Refiner -> (sigmas) -> SamplerCustomAdvanced
参数 类型 默认值 范围 说明
sigmas SIGMAS - - 原始噪声序列
extra_steps INT 1 0 ~ 15 低噪区间额外增加的步数
start_at_sigma FLOAT 0.7 0.0 ~ 20.0 启动加步的 Sigma 阈值
end_at_sigma FLOAT 0.0 0.0 ~ 5.0 结束细化的 Sigma 边界
spacing COMBO cosine cosine / linear / exponential 尾部插值分布曲线

spacing 曲线：

6. H3 Tiled Sampler（空间分块采样）

原理： 768p/2K 高分辨率上采样精修时，H3 DiT 打包自注意力的 token 数远超训练分布，导致显存爆炸或画面质量下降。本节点沿 H 或 W 轴空间分块，每块独立采样后 cosine 窗口融合，严格保持 H3 视频/音频独立模态，音频 passthrough 不参与采样。

接线： 替代 SamplerCustomAdvanced，接入 noise / guider / sampler / sigmas / latent_image。

适用场景： 二采高清精修（低噪起步），不适用重去噪（纯噪声起点会破坏全局一致性）。

参数 类型 默认值 范围 说明
noise NOISE - - H3 噪声生成器
guider GUIDER - - H3 CFG/STG guider
sampler SAMPLER - - 采样算法
sigmas SIGMAS - - H3 噪声调度
latent_image LATENT - - H3 video latent
bypass_tiling BOOLEAN False - True 时单次采样，等同 SamplerCustomAdvanced
tile_axis COMBO auto auto / H / W 分块轴，auto 取较长轴
n_tiles INT 2 1 ~ 8 分块数，1 等同 bypass
tile_overlap INT 8 0 ~ 32 相邻块在 latent 域的重叠 token 数
max_size_for_no_tile INT 24 8 ~ 256 目标轴 ≤ 此值时自动 bypass
target_frames INT 17 1 ~ 512 最小帧数保护（非截断），不足时补齐
frame_padding_mode COMBO replicate_last replicate_last / zero / error 帧数不足时的填充方式
debug BOOLEAN False - 打印每个 tile 的 shape 和 value range

安装

  1. 将 ComfyUI-YCNodes-MiniMax-H3 目录放入 ComfyUI/custom_nodes/ 下。
  2. 重启 ComfyUI。
  3. 节点面板搜索 H3 即可找到全部节点。

推荐工作流接线

一采（低分辨率）：

[CLIP] ─────────────────────────────────────────────────────────┐
[图像] -> [MiniMaxH3ImageToVideo / MultiParams] -> COND ────────┤
                                                                ├─> [H3PromptRelay] -> MODEL ─┐
[CLIP] ─────────────────────────────────────────────────────────┘                            │
                                                                                             ├─> [H3DynamicCFGScheduler] -> MODEL -> [采样器]
[BasicScheduler] -> [H3SigmaRefiner] -> SIGMAS ──────────────────────────────────────────────┘

二采（高清精修，Tail 节点续跑，Tiled 采样）：

一采LATENT -> video_latent ─┐
[图像] -> [MiniMaxH3ImageToVideoTail] -> COND ─┐
[CLIP] ────────────────────────────────────────┤
                                                ├─> [H3PromptRelay] -> MODEL -> [H3DynamicCFGScheduler] -> MODEL ─┐
                                                LATENT ───────────────────────────────────────────────────────────┤
                                                                                                                   ├─> [H3TiledSampler] -> LATENT
[BasicScheduler] -> [H3SigmaRefiner] -> SIGMAS ────────────────────────────────────────────────────────────────────┘

ComfyUI-YCNodes-MiniMax-H3 (yichengup/ComfyUI-YCNodes-MiniMax-H3)

Searching Database…

243 ·GitHub
ComfyUI-YCNodes-MiniMax-H3
What is this?This is a ComfyUI custom node pack built specifically for the MiniMax H3 video model, adding 6 nodes for second-pass conditioning, timed prompt control, attention-field constraints, dynamic CFG scheduling, low-noise detail refinement and tiled sampling.
Is this a standalone app or does it plug into something else?It is a plugin folder you drop into an existing ComfyUI installation - it only works alongside the official MiniMax H3 nodes and model, not on its own.
How do I install these nodes?Copy the ComfyUI-YCNodes-MiniMax-H3 folder into ComfyUI/custom_nodes/, restart ComfyUI, then search for 'H3' in the node panel to find all six nodes.
Do I need any extra libraries besides PyTorch?No third-party dependencies are needed - the pack only requires PyTorch - but you must already have ComfyUI running with the official MiniMax H3 model, CLIP and VAE loaded.
Can I use the Tiled Sampler for a full re-noise generation?No, it is meant for low-noise, high-resolution refinement passes (768p/2K); starting it from pure noise breaks global consistency across the tiles.
Do I still need the official MiniMax H3 nodes too?Yes, these nodes extend and patch the official MiniMaxH3ImageToVideo node and its multi-param variant, so the base H3 workflow has to already be set up.
What does the Image to Video (Tail) node fix?The official MiniMaxH3ImageToVideo node always starts from pure noise, so it can't continue a previous render. The Tail node accepts a first-pass latent and recomputes the keyframe anchors so you can run a second, higher-detail pass.
How does H3 Prompt Relay change prompts over time?H3 packs text, conditioning, audio and video into one self-attention sequence instead of using cross-attention, so this node masks the video-to-text attention path with a time-decay penalty, letting prompt segments separated by '|' each control their own time window.
What problem does the Distance Attention Patcher solve?In wide shots, limbs and faces can get blended into the background during denoising. This node applies a spatio-temporal Gaussian receptive-field mask in the early-to-mid steps so local details stay distinct from large background areas.
Why use the Sigma Refiner?It adds extra sampling steps only in the low-noise tail of the schedule, smoothing out pixel noise and mosaic artifacts on fast-moving edges without touching the early high-noise steps.
What are similar projects?ComfyUI-Ref2VA-VSA, FreeVideo, LTX-Video, ComfyUI-MiniMaxH3-TimelineDirector, Comfyui-MMH3-UltimateUpscale, Comfyui_Minimax_h3_latent_Upscaler, ComfyUI-H3-FaceRefine, LTX-2
Which topics is it in?comfyui-nodes, image-to-video, comfyui, attention-mechanism, diffusion-models, video-processing, gpu-acceleration, video-generation, artificial-intelligence, inference, generative-ai, pytorch
Creator
yichengup
Size
0.1 MB
Stars
243
Updated
CommitSep 15ReleaseInitialSep 07
Age
2mo
Commits · 90 Days