一键式 MiniMax H3 长视频自动化生成节点：分段推理 + 段间续接锚定 + 提示词时间轴切片 + 二次采样（二采）+ 接缝修正 + 面部修复。
在显存有限的情况下，将长视频拆分为多段独立推理，通过叠加增强方法实现段间无缝衔接，同时按时间轴自动切分提示词，让每段生成内容与提示词节奏对齐；对音视频参考做同样切片并对齐；当前段只有被引用的参考参与推理。
H3 的显存需求随分辨率、时长（每 +5s 翻倍）、精度（fp8→bf16）指数增长，所以显存有限是相对的——32GB显存 用 bf16 生成 15 秒 1080p 也会溢出降速，分段虽然增加了锚定帧的开销，但峰值显存只取决于单段长度、与目标总长无关，实际推理时间反而比一次生成长视频更快。
支持二次采样。视频续写、视频前推、双视频衔接。
支持latent缓存存取，方便推理过程中因某种原因导致推理中断后，快速跳过已推理分段，缓存文件以分段为单位存储，在采样节点上游参数不变的情况下，读取已有 latent cache 文件。
缓存磁盘占用：新增目录级上限，默认 32 GB，超出自动清理最旧文件（可用环境变量 H3_CACHE_MAX_GB 调整，设 0 关闭）
- 开启Minimax_H3_AutoContext_Sampler节点上的 clear_cache 参数，这会在采样开始时，强制重新建立本节点缓存文件。
- 手动删除缓存目录中的对应文件夹（\ComfyUI\output\cache），文件夹名为“node_” + “节点ID”。
- 面部修复节点 - 详细说明：中文 | English
Minimax_H3_Face_Cut：检测与裁剪，分镜 + YOLO 检测 + 可选 SeC-4B 追踪。Minimax_H3_Face_Resample：精修，主采样同款模型做块级 img2img 重采样（块结构镜像主采样分段 + 块间锚定）。Minimax_H3_Face_Blend：贴回，精修脸按几何账本与 mask 逐像素贴回原画面。
-
语义桥（Semantic Bridge）
- 集成 MiniMax-H3-Semantic-Bridge：将 SenseNova U1.5 教师桥蒸馏出的 ~11MB 学生适配器混合进 H3 条件，增强提示词遵循度（空间关系 / 计数 / 材质 / 反射等），推理时无需 SenseNova 参与。
⚠️ 语义桥并非通用方法，部分情况会产生劣化，非必要不要开启。上游 v1 仅验证 FL2VA / 文本路径；Ref2VA 参考路径（ref_video/ref_audio，含口型同步）未验证，实测可能劣化口型与演唱表现，使用前请自行开 / 关 A/B 对比。
-
缓存与性能
- 支持 checkpoint / 加速 LoRA / 改精度 / 挂函数级补丁后的缓存检测。
- 固定提示词时，不再每块重载文本编码器；并加强指纹校验（像素内容指纹），避免换图假命中。
-
注意力校正节点
- 新增
Minimax_H3_TST_AttentionPatch注意力校正节点：H3 TST 注意力校正 — 谱张力诊断，抑制时序闪烁 / 小脸崩坏。 tau强度建议 0.2-0.3，需放在其它 attention patch 下游。
- 新增
- 参数节点兼容性修复：修复 H3Parameter 的 total_frames / chunk_frames / context_frames 连接 Math Expression 等节点后，分段预估请求死循环、ComfyUI 页面卡死的问题。
- 新增 video_guide 参数：优化视频续写、视频前推、双视频中间衔接，支持分段。非 none 时，采样节点对应参考端口会按 context_frames 强制裁剪；引用规则同普通参考，需在提示词中声明。
- Latent 缓存重构：取消手动缓存目录，改为按“node + 节点 ID”自动生成唯一目录，避免缓存互相覆盖。缓存按分段建立与校验；未改变对应分段提示词及相关参数时复用旧缓存，新增分段自动建立缓存；下游二采同样保留并复用旧缓存。提示词变更后，该分段及后续分段强制重建，下游节点同样处理。
- 新增 ignore_latent_hash：可忽略 input_latent 哈希校验，避免会改变 latent 判断信息的节点导致缓存误失效。不改变 latent 噪声特征的节点可设为 false, 已测试 Minimax_H3-LatentUpscaler_Adv节点 。
- 哈希检测增强：完善哈希检测参数，修复采样器上游 parameter 改变导致的张量不匹配。
- 接缝校正优化：Minimax_H3_Seam_Correction 移除镜头检测模型，改用 PySceneDetect（纯 CPU，无潜在污染），避免采样节点预览白屏
| 节点 | 说明 |
|---|---|
| Minimax_H3_AutoContext_parameter | 参数组节点：集中管理提示词/分段/分辨率/音频等参数，输出 parameter，并实时预览「预计分段」 |
| Minimax_H3_AutoContext_Sampler | 主节点：分段推理 + 续接锚定 + 采样（一采/二采共用） |
| Minimax_H3_Seam_Correction | 接缝修正节点：对解码后视频的段间接缝做像素域修正 |
| Minimax_H3_Face_Cut | ① 检测与裁剪: 分镜 + YOLO 检测 + 可选 SeC-4B 追踪, 逐帧平滑窗口裁成统一 res² 小图 |
| Minimax_H3_Face_Resample | ② 精修: 主采样同款模型做块级 img2img 重采样 (块结构镜像主采样分段 + 块间锚定) |
| Minimax_H3_Face_Blend | ③ 贴回: 精修脸按几何账本与 mask 逐像素贴回原画面 (零 VAE) |
| Minimax_H3_TST_AttentionPatch | 注意力校正：H3 TST 注意力校正 — 谱张力诊断，抑制时序闪烁、小脸崩坏（效果有限） |
用法：
parameter 节点 --parameter--> 主节点。提示词在 parameter 节点填写，主节点通过parameter（必选）接收。
- 按
total_frames/chunk_frames（帧单位）拆分为多段，帧数建议取 5、22、39、56、73、90… - 末段自动加长补齐，避免出现过短的尾段
fps仅用于音频同步和提示词内秒数换算
- 叠加增强：非首段自动"接力"上一段的结尾画面，新增内容从上一段结束的位置和动作自然延续，消除接缝处的停顿或位置跳变
- 上一段结尾作为运动参考传给当前段，帮助延续运动方向与速度
- 上一段音频也作为"之前的内容"传入，帮助声音自然延续
- 段间音频平滑淡化，与视频帧数对齐
帧数规则：
total_frames/chunk_frames/context_frames都取 5、22、39、56、73、90…（17 的倍数加 5），节点会自动对齐，一般无需手动计算。
| 模式 | 说明 |
|---|---|
| Clip_Tag | 按用户自定义标签（如 段1/段2）切分提示词，每个标签对应一个独立视频段；段时长由提示词内容决定（标签后时长 > 段内时间标记 > total_frames/fps 兜底）。 |
| timeline | 按显式时间标记（如 0-2s/2-6s）切分提示词，每个时间区间对应一个视频段；段时长 = 区间长度 × fps 并自动吸附到合法网格；忽略 total_frames 和 chunk_frames，完全由提示词决定总时长。全局段（【全局】）保留在原始位置，不会集中提取。 |
| sequential | 将提示词按句读顺序均匀分配到整个视频时间轴上，不切分提示词本身；视频分段仍按 chunk_frames 进行。 |
| global | 整段提示词用于所有视频段（剥离 【全局】 标记后），视频分段按 chunk_frames 进行。 |
在
Clip_Tag和timeline模式下，total_frames和chunk_frames参数被忽略（段长由提示词决定），仅当模式降级（如未检测到标签/时间标记）时才会回退使用这些值。
- 按用户自定义标签（如
段1/段2/段3）切分提示词，每段 = 一个 chunk = 该段全部提示词 - 段时长由提示词内容决定（三层优先级）：
- 标签行紧跟的时长（如
段1:0-5秒→ 5 秒；段1:3-8秒→ 5 秒） - 段内时间标记的最大结束值（如
【0-2秒】+【2-5秒】→ 5 秒） total_frames / fps默认值兜底（单段时总帧数贴合total_frames）
- 标签行紧跟的时长（如
- 段内时间标记是相对时间（每段从 0 开始），不是全局绝对时间
- 非首段会多生成一段重叠帧用于衔接，生成后自动裁掉
- 总时长自动对齐目标总帧数，尽量贴近预期时长
- 推理时标签本身会被去除，其余提示词内容根据
prompt_format输出
- 自动识别每段提示词里用到的参考图/视频/音频，只把被引用到的素材传给该段
- 视频与其配对音轨绑定，避免画面/声音串扰
- 主节点
latent_input接入一采 latent（或经 latent 放大节点）即进入二采模式 - 二采分辨率以输入 latent 为准（忽略 width/height），实现低清一采 → 高清二采
denoise控制重绘强度；sigmas支持自定义 sigma 序列（与SamplerCustomAdvanced同款）lock_audio：二采只重画视频、复用一采音频
drive_audio（AUDIO，可选）+audio_drive开关- 开启后视频跟随这条音频生成，输出音频 = 源音频本身（口型/节奏由它驱动）
cd ./ComfyUI/custom_nodes
git clone https://github.com/supElement/ComfyUI_MinimaxH3_AutoContext.git在 ComfyUI Manager 中搜索 ComfyUI_MinimaxH3_AutoContext，点击 Install。
首次安装（只想使用旧版 classic 分支）：
git clone -b classic https://github.com/supElement/ComfyUI_MinimaxH3_AutoContext.git
已安装，从 main 切到 classic：
git fetch origin → git checkout classic → git pull
| 参数 | 默认值 | 说明 |
|---|---|---|
| long_prompt | — | 提示词（传给主节点推理，同时用于「预计分段」预览） |
| clip_mode | Clip_Tag |
提示词映射到视频段的方式：Clip_Tag / timeline / sequential / global。Clip_Tag 和 timeline 模式下忽略 total_frames 和 chunk_frames。 |
| clip_tag | 段1 |
Clip_Tag 分割标签模板（必须以数字序号结尾），仅 clip_mode=Clip_Tag 时生效 |
| prompt_format | official |
提示词输出格式：official / legacy / raw。official 使用 MiniMax H3 官方 [Shot] 格式，legacy 为旧式时间标签，raw 原样输出（用于 Clip_Tag 模式） |
| crop_mode | stretch |
参考图/首尾帧/参考视频缩放裁剪：center / stretch / none |
| ref_sync_mode | segmented |
参考视频/音频是否按段切片：global（每段使用完整素材） / segmented（按段的时间比例切片） |
| width × height | 960×544 | 一采分辨率（二采时被 latent_input 覆盖） |
| total_frames | 362 | 生成总帧数（17n+5）；在 Clip_Tag/timeline 模式下仅作为兜底（无标签/无时间标记时），最终被各段之和覆盖 |
| fps | 24 | 帧率，用于音频同步和提示词秒数换算 |
| chunk_frames | 90 | 每段生成帧数（17n+5），仅在 sequential / global 模式下生效 |
| context_frames | 22 | 段间续接帧数（17n+5：5/22/39/56…），建议 22 以上 |
| lock_audio | true |
二采时锁定音频区（noise_mask audio=0）：只重新采样视频、保持一采音频不变 |
| audio_drive | false |
音频驱动开关，开启后视频跟随 drive_audio 生成 |
| video_guide | none |
视频延长参数，支持分段。 none: 不启用；pre_guide: 视频续写（采样节点 ref_video_0 或 + ref_video_audio_0 端口）；post_guide: 视频前推（采样节点 ref_video_0 或 + ref_video_audio_0 端口）；pre_post_guide: 双视频中间衔接（采样节点 ref_video_0 或 + ref_video_audio_0 端口，ref_video_1 或 + ref_video_audio_1 端口）。锚定帧数由 context_frames 决定。注意：非none时，采样节点的对应参考端口的参考会被强行剪切为context_frames参数中设置的数值。参考引用逻辑与普通参考相同（提示词中声明了，才会引用） |
| semantic_bridge | false | 语义桥开关：将 SenseNova 蒸馏的 ~11MB 学生适配器按 C = H + alpha*(S-H) 混合进条件张量，增强提示词遵循度。只变换条件，不动模型权重；段间续接锚定与参考通道不受影响。适配器放入 models/semantic_bridge/ |
| semantic_bridge_adapter | none | 语义桥适配器文件（models/semantic_bridge/ 下的 .safetensors）。none = 禁用。启动后新放入的文件需重启 ComfyUI 才会出现在下拉框 |
| semantic_bridge_alpha | 0.10 | 融合强度。官方推荐起点 0.10，官方 A/B 示例用 0.15，建议在 0.10~0.15 之间微调 |
| semantic_bridge_magnitude | per_token | 融合前幅度对齐：per_token 逐 token RMS 对齐（官方推荐）/ global 全张量标量对齐 / none 不对齐 |
节点上实时显示「预计分段」预览（前端 JS 计算，不参与推理）。
关于语义桥
- 上游项目：Speach1sdef178/MiniMax-H3-Semantic-Bridge（适配器下载：HuggingFace）
- 连接方式：无需改工作流接线 —— 在 parameter 节点开启
semantic_bridge并选择适配器即可，主采样节点逐段自动应用 - 影响范围：只混合文本/FL2VA 条件张量；段间续接锚定与参考素材通道不受影响
- 适配器安装：下载
.safetensors放入ComfyUI/models/semantic_bridge/（目录自动创建），重启 ComfyUI 后在semantic_bridge_adapter下拉框中选择 - 缓存行为：桥参数参与分段缓存指纹，改 alpha / 换适配器 / 开关桥后对应段自动重建
⚠️ 适用范围：上游 v1 仅验证 FL2VA/文本路径；Ref2VA（参考视频/音频）未验证，实测可能劣化口型与演唱，请自行 A/B
| 参数 | 默认值 | 说明 |
|---|---|---|
| model / vae / audio_vae / clip | — | MiniMax H3 模型组件 |
| parameter | 必选 | 参数组输入（来自 parameter 节点） |
| sampler | 可选 | 外部采样器对象（SAMPLER），覆盖内置 sampler_name/scheduler |
| sigmas | 可选 | 自定义 sigma 序列（SIGMAS），优先级最高 |
| latent_input | 可选 | 二采输入 latent（接入即开启二采） |
| info | 可选 | 参数继承输入（多采串联，保证分段一致） |
| first_frame / last_frame | 可选 | 首/尾帧锚定（FL2VA） |
| video_context_denoise | 0.0 | 段间续接强度（仅非首段）：0=精确延续上一段结尾，1=重新生成，中间值=软混合。二采接 SplitSigmas 时建议设 1 避免花屏 |
| seed | 0 | 随机种子（control_after_generate） |
| steps / cfg | 30 / 1.0 | 采样步数 / CFG |
| sampler_name / scheduler | euler / simple | 内置采样器 / 调度器 |
| denoise | 1.0 | 重绘强度（1=全量重采样，越小保留越多原结构） |
| enable_cache | true | 存储\读取latent缓存，自动在 “\ComfyUI\output\cache” 目录下创建以“node+节点ID” 命名的文件夹，上游节点或参数发生变化时会覆盖已有latent缓存文件 |
| clear_cache | false | 强制重建latent缓存文件 |
| ignore_latent_hash | false | 忽略输入端口input_latent 的哈希值校验。实用场景：有些latent处理节点会改变latent判断信息，使latent的微小变化导致缓存不可用，浪费推理时间，此时建议设置为true |
| ref_image_N / ref_video_N / ref_video_audio_N / ref_audio_N | 可选 | 参考素材（Autogrow 动态端口） |
| drive_audio | 可选 | 音频驱动源 |
| 输出 | 说明 |
|---|---|
| latent | 拼接后的音视频 latent，接 VAE Decode，或放大后接二采 |
| denoised_latent | 干净的 latent 输出，用于二采接力 / 预览 |
| info | 分段参数（Dict），传给下一个主节点的 info 输入，保证多采分段一致 |
parameter 节点 ──parameter──> 主节点(一采, 864×480)
└─ latent / denoised_latent ──> [分离 AV] ──> video_latent ──> latent 放大 ──> [合并 AV] ──> 主节点(二采).latent_input
二采节点: parameter 共用 (或 info 继承)，可选 denoise 0.4~0.6
- 二采分辨率以
latent_input为准，忽略 parameter 的 width/height
⚠️ 音频约束：高低频只对视频生效（音频段间衔接需要完整采样），音频请保持完整采样。
一采节点: 完整采样 (不接 high_sigmas，audio 完整去噪)
→ denoised_latent → 分离放大 video (audio 不动) → 合并 → 二采.latent_input
二采节点: sigmas ← low_sigmas (只跑低 sigma 段提细节)
lock_audio = True (复用一采完整音频)
video_context_denoise = 1.0 (续接区随新增区一起重绘，避免花屏)
💡 二采
video_context_denoise：接 SplitSigmas 时若设 0（精确延续），续接区与已重绘的新增区在边界可能花屏；设 1.0 让续接区同步重绘即可避免。接缝略有不连续时可降到 0.3~0.5 折中。一采保持默认 0。
| 参数 | 默认值 | 说明 |
|---|---|---|
fix_color_preset |
"medium" |
色彩/曝光处理档位off：不处理；low：逐通道亮度增益，修正量减半，最保守，无色偏；medium：逐通道亮度增益，仅修接缝电平跳变（推荐）；high：MKL 线性色彩迁移，统计窗口更长，运动大时更稳；max：全片逐帧亮度归一化，消除段内渐变漂移，但会削平画面本身明暗变化（如天黑/进隧道），近黑帧无效（日志报告）。 |
fix_motion_preset |
"off" |
接缝连续性（光流对齐+融合）档位off：不处理（建议先用色彩档位观察效果）；low/medium/high/max：档位越高参与融合的帧数与强度越大，但越容易带来轻微糊感或呼吸感。 |
fix_flash |
false |
闪帧处理（边界处瞬时亮度突跳）。独立开关，采用时域融合逻辑。若画面有闪电、爆炸等合理快速明暗变化，抑制会削平这些效果。即使 fix_motion_preset=off 时仍可独立生效。 |
flash_threshold |
0.30 |
瞬态修正筛选阈值（异常像素占比），值越小越激进（修正更多帧），推荐 0.20 ~ 0.40。 |
cut_threshold |
15.0 |
PySceneDetect 的灵敏度阈值（范围 5.0 ~ 50.0），值越小越敏感，推荐 10 ~ 20。 |
blend_frames |
2 |
接缝处电平渐变窗口（帧，0~8）：曝光对齐后，把边界前后各 blend_frames 帧的亮度过渡按平滑斜坡拉平；值越大过渡越缓、越自然，但运动大的镜头过大会带来轻微糊感/呼吸感；0 表示关闭。 |
use_gpu |
true |
使用 CUDA GPU 进行统计、色彩变换与光流计算（若不可用则自动回退 CPU）。 |
用法：
VAE Decode → H3_Seam_Correction → Save/Video。
⚠️ 提示：本节点只做画面接缝修正，无法修复二采上游产生的伪影。
0-5s: ...
5-10s: ...
integrated_multimodal_description
....
overall_soundscape
含
0-5s标记的段落按时间切分，无标记段落（风格/音效/禁止项）自动拼入每个窗口。
整段提示词用于所有分段，适合全程同质动作的一镜到底。
clip_mode设为Clip_Tag，clip_tag填写标签模板（必须以数字序号结尾）。
标签模板示例
| 模板 | 匹配 |
|---|---|
段1 |
段1 / 段2 / 段3（前缀"段"+数字） |
A01 |
A01 / A02 / A03（前缀"A"+数字） |
[片段001] |
[片段001] / [片段002]（前缀"[片段"+数字+后缀"]"） |
标签写法：标签独占一行作为分割点，标签后推荐换行。不换行时也能处理（跳过分隔符取段内容）：
段1:3s
视频：
...
音频设计：
...
段2:3-8s
视频：
0-2秒：
...
2-5秒：
...
音频设计：
0-5秒：...
段时长规则（三层优先级）：
- 标签行紧跟的时长：
段1:0-5秒→ 5 秒；段1:3-8秒→ 5 秒（时长标记会从提示词中去除） - 段内时间标记 0 基：
【0-2秒】+【2-5秒】→ 5 秒 - 都没有 →
chunk_frames / fps兜底
prompt_format 选择
official/legacy：段内时间标记自动转为段内相对坐标渲染raw：去标签后原样输出，时间标记保持不变（适合用大模型生成的结构化提示词）
以下注意事项不适用于简单的、始终有效的提示词场景（即所有分段共用同一个提示词，global 模式）， 比如：口播数字人（当然，台词需要分段）、视频中的镜头/构图变化不大，或视频替换角色等提示词通用的场景。
使用分段推理（Chunk）时，请务必遵守时序排他性原则——每一段提示词只能描述该段"正在发生"的、相对于上一段末尾的新变化。
- 分段即"接力"：第 N 段生成时，它的起始画面状态（位置、动作姿态、镜头位置）完全由上一段末尾的"锚定帧（Context Frames）"隐式提供。你不需要在提示词里重复描述这个起始状态。
- 禁止"回叙"与"重叠"：第 N 段的提示词绝对不可以重复描述第 N-1 段已经完成的动作或镜头运动。如果重复描述，模型接收到的指令就会与锚定帧的画面产生逻辑冲突（指令冲突），导致生成画面卡顿、运动逻辑错乱或动作重复。
- 边界清零：切换分段时，请把上一段的"正在进行的动作"清零。新的一段提示词，应当像"按下快门后的新指令"一样，仅针对当前新时间段内发生的位移、动作或新元素出现。
❌ 错误写法（冲突重叠）
段1：3秒
"物体 A 向位置 B 移动"
段2：3-6秒
"物体 A 移动到位置 B 后，正在位置 B 转身"
问题分析：第 1 段结束时，锚定帧显示物体 A 已经到达位置 B 且刚停稳。但第 2 段提示词强行要求"物体 A 移动到位置 B"，这与锚定帧"已到达"的静态结果冲突，模型会试图"重新移动"，造成鬼畜或跳帧。
✅ 正确写法（无缝递进）
段1：3秒
"物体 A 向位置 B 移动，并最终停在位置 B"（强调动作闭环）
段2：3-6秒
"站稳后，物体 A 缓慢转动方向"（直接描述上一段结束后的新动作）
正确逻辑：第 2 段完全抛弃对"移动过程"的描述，默认"停在 B 点"是既定事实，只描述接下来的"转动"新动作，模型就能利用锚定帧完美续接。
🚀 总结成一句话：上一段的末尾是"结果"，下一段的开头是"结果之后的新动作"，别把"导致结果的过程"写到下一段里去。
使用分段推理并搭配参考图/视频（image1、video1 等）时，请务必遵守逐段引用声明原则——每一段提示词都必须独立且完整地声明该段所需要的全部引用素材，引用不会被"记忆"或"继承"到下一段（当前段只有被引用的参考参与推理）。
- 无全局记忆：节点解析当前段提示词内写明的引用标签，精准判断该段需要哪些素材。上一段写了 image1，只代表上一段调用了它；到了下一段，会重新扫描。
- 不写则不传：如果第 N 段没再写 image1，该段就不会传入这张参考图，导致角色/物体不一致。
❌ 错误写法（隐式继承）
段1[3秒]：image1 是物体A，物体A正在向前移动。
段2[3-6秒]：物体A停下，转身看向镜头。（没写 image1）
✅ 正确写法（逐段显式）
段1[3秒]：image1 是物体A，物体A正在向前移动。
段2[3-6]：image1 是物体A，物体A停下，转身看向镜头。