ComfyUI-FeiHou-Easy-H3
MiniMax H3 generation for ComfyUI with an embedded 9-image, 3-video, and 3-audio reference gallery.
Nodes (16)
MiniMax H3 with the whole reference gallery built in
The node that deletes the seam between two H3 shots
Make your H3 video come out the exact length of its audio
A second sampling pass, not a sharpening filter
The model room that packs your H3 bundle
The debug LoRA stack that feeds Easy H3
The node with no inputs that holds nine images, three videos and three audio clips
Bring your own loader chain into the bundle
The bridge back to boring, standard nodes
Render a whole music video shot-by-shot without touching the node between runs
See what your prompt actually became
One transformer to serve both passes
Stop doing megapixel math in your head
Your own noise, your own scheduler, and a draft you can actually look at
The refine pass that also hands you the VAE, the audio and the clock
The whole generator, minus the media gallery bolted to its face
ComfyUI-FeiHou-Easy-H3
English | 中文
这是一个将参考媒体加载内嵌到主节点内的 MiniMax H3 ComfyUI 节点包。
主节点把参考媒体加载全部收进节点内部，不再需要外接 Load Image、Load Video、Load Audio 节点：
- 9 个图片槽位，固定 3 × 3 九宫格；
- 3 个视频槽位；
- 3 个独立音频槽位；
- 点击槽位选择文件，也可以把文件直接拖入槽位；
- 图片和视频在节点内预览，音频显示文件名；
- 已上传文件随工作流记录，重新打开工作流后仍可恢复；
- 参考模式继续支持在提示词里输入
@选择<Picture i>、<Video i>、<Audio i>； - 视频原有音轨仍与该视频自动配对，3 个音频槽位作为独立参考音频；
- 默认 24 FPS、10 秒；参考图尺寸可选短边 480、544、640、736、768、832、928、1024、1088；
- 高级选项提供“强制卸载（含采样后缓存回收）”和可选“完整低显存分块（实验）”：前者在采样器结束、VAE 解码前回收未使用的缓存，后者对 H3 的 QKV、注意力、MLP/SwiGLU 和输出头执行完整分块；启用后不要再串联
ModelAttentionBackend / comfy kitchen attention； - 提示词优化支持智谱、xFlow-API 聚合、Ollama、阿里云、DeepSeek 和自定义 OpenAI/Gemini/Ollama 兼容 API；
- 提示词优化也支持本地 GGUF、完整 Transformers 模型目录，以及带内置架构识别的裸
.safetensors；标准版内置 Qwen3 0.6B、1.7B、4B、8B、14B、32B 和 Mistral 7B Instruct v0.3 配置，改文件名不影响识别； - 内置提示词方案之外，还可创建、编辑和选择自定义方案。
节点
标准版新增实验功能：制作包分镜加载器使用说明。可读取文件夹 / ZIP 内的 Shotlist，按镜应用提示词、歌曲截取和引用图，并通过原生队列递增依次生成。
加载LoRA（旁路，仅模型）（用于调试）：完全沿用FeiHou LoRA Stack (Merge/Extract)的原生画布堆栈样式，可动态添加、启停、排序多个 LoRA；FeiHou Easy H3 Loader：从左侧接收 LoRA 堆栈，并在内部加载 FL2VA/REF2VA 模型和应用 LoRA，同时加载文本编码器、视频 VAE 和音频 VAE；ComfyUI-FeiHou-Easy-H3：主生成节点及内嵌媒体面板；FeiHou Easy H3 Model Adapter：接入外部标准 ComfyUI 模型加载链；FeiHou Easy H3 Output：拆出 Conditioning、Latent、视频 VAE、音频 VAE、FPS 和最终提示词；FeiHou Easy H3 提示词预览：显示 H3 Context 携带的最终扩写 / 反推提示词；FeiHou Easy H3 接续合并：保留接续尾部、裁去重叠画面和音频，将tail_latent交给肥猴工具箱 Video Combine V2保存。最后一段完成后由 V2 合并完整视频；接线和控制说明见制作包文档。
节点分类为 FeiHou Easy H3，类名使用独立的 FeiHouEasyH3* 前缀，可与原版 ComfyUI-MiniMaxH3-Easy 同时安装，不会发生节点 ID 或提示词优化路由冲突。
使用
- 把当前
Easy H3整个文件夹放到ComfyUI/custom_nodes/；也可以将目录改名为ComfyUI-FeiHou-Easy-H3。 - 更新到包含官方 MiniMax H3 节点的新版 ComfyUI。
- 重启 ComfyUI，并在
FeiHou Easy H3分类中添加节点。 - 把“加载LoRA（旁路，仅模型）（用于调试）”放在 Loader 左侧，将它的
lora_stack输出接到 Loader 左侧的“LoRA 堆栈”输入；Loader 再连接主节点。LoRA 不再串联到主节点的model输出链路上。 - 选择“参考生成视频”模式后，九宫格、3 个视频槽和 3 个音频槽都会启用。
提示词配置位于 ComfyUI“设置”左侧的 🐵Easy H3 独立插件分组。API 设置和“提示词优化规则”直接显示在右侧设置页，不再打开二级窗口；Base URL 可修改，API Key 粘贴后自动保存，预置服务不附带 Key 或模型。主节点关闭“高级选项”时不显示、也不执行 API 和提示词方案；打开后先选择已配置的 API 接口，再选择方案。API 未启用时方案不生效。API 密钥保存在 ComfyUI 用户目录下的本插件配置文件中，不随工作流导出。
本地模型依赖
Manager 安装时会执行依赖安装入口；手动解压后可在 Easy H3 设置→本地模型使用“检查依赖”和“安装/修复依赖”，或双击节点目录中的 install-local-llm.bat。安装器使用 ComfyUI 的 Python，按环境选择 GGUF 包；安装完成后按提示重启。详细步骤和支持范围见本地模型依赖安装说明。
自定义 API
自定义 API 可直接填写完整的 HTTPS 地址，例如 https://api.example.com/v1，不需要维护域名白名单文件。API Key 和模型仍在 Easy H3 设置页中配置，并保存在本机 ComfyUI 用户目录中，不随工作流导出。
外部提示词 API 仍要求 HTTPS；本机 Ollama 可使用 http://localhost:11434、127.0.0.1 或 ::1。API 设置、模型发现和即时提示词优化路由仍只接受运行 ComfyUI 的本机访问。
开发时可自行维护本机的同步配置；本仓库不会提交本机路径、API Key、上传媒体或输出元数据。
在“图生或首尾帧”模式下，只使用九宫格前两个图片槽：一张图按高级选项作为首帧或尾帧，两张图作为首尾帧。切换模式不会删除已选的其他参考素材，返回参考模式后可继续使用。
RefMod 参考包接入
主节点 ComfyUI-FeiHou-Easy-H3 和拆分的 FeiHou Easy H3 Setup 均提供可选的 refmods 输入。安装 ComfyUI-MiniMaxH3Mod，将其 Load H3 RefMods 的 mods 输出直接接入，选择 Easy H3 的“参考生成视频”模式；一采、二采仍按原来的方式连接。也可直接连接其 Create / Master 的 mods 输出。无需再对同一份参考执行 Apply 或 Text Encode，否则会重复注入。
RefMod 不占媒体面板的 9 图 / 3 视频 / 3 音频槽位，但会增加总参考 token 和显存开销。加载器的强度、copies、模态选择由上游处理；Easy H3 保留其处理后的 latent，并解码视觉参考供 H3 文本视觉编码器识别，不对参考 latent 再编码。保存的 Apply / Step Curve 配置不会自动应用。高级“仅文本参考”开启时，同普通素材一样，只保留文本视觉呈现，不注入 RefMod latent。
编号规则为 RefMod 在前、普通素材在后，图片 / 视频 / 音频各自连续编号。连接原版 Load H3 RefMods / Axis 后，主节点和 Setup 的 @ 菜单会直接显示已启用参考包的类型、编号和名称，无需上传占位素材。例如 Kirara 为 video 类型时，直接选“视频1 · Kirara”；再上传普通视频则顺延为“视频2”。8 份 image 类型 RefMod 对应 <Picture 1>～<Picture 8>，随后 9 张普通图片对应 <Picture 9>～<Picture 17>；8 份 video 类型 RefMod 则对应 <Video 1>～<Video 8>，普通图片仍从 <Picture 1> 开始。copies 和包内模态成员分别占编号，强度为 0 或被过滤的参考不占编号。
RefMod 引用随工作流保存并绑定参考包来源，删除普通上传素材不会破坏它；关闭或移除所引用的包会提示引用失效，避免错误绑定到普通视频。之前用临时视频创建的旧引用仍绑定临时素材，需删除旧引用并从新 @ 菜单重新选择 RefMod。多张照片堆叠成的包可能属于 video 类型。将 Easy H3 Output.reference_map 接到提示词预览或文本显示节点可查看实际编号，日志也会输出该表。菜单只读取包的元数据，不加载模型或解码视频；直接连接 Create / Master 时仍可手写官方标签。不同人物建议分别制作参考包；多参考身份保持和生成质量仍需实测。
只接视觉 RefMod、不上传普通素材也可使用参考模式；只接音频仍需补充图片、视频或视觉 RefMod。视频 RefMod 的文本视觉呈现按 24 FPS 重建、2 FPS 取样，与上游 Text Encode 默认规则一致，不还原原始时间戳。图生 / 首尾帧模式接入有效 RefMod 会提示切换参考模式。新增输入与 Output 编号表输出均追加到原有接口，旧工作流连接保持不变。
媒体限制
- 参考图片：最多 9 张；
- 参考视频：最多 3 个；
- 独立参考音频：最多 3 个；
- 参考模式至少需要一张图片或一个视频，不能只提供音频；
- 视频帧和同步音轨的编码、排序及标签规则与 ComfyUI 官方
MiniMax H3 Reference to Video节点一致。
改编、致谢与许可
本项目是改编版本，并非独立重写。H3 节点上游来源为 nkxx188/ComfyUI-MiniMaxH3-Easy，原作者为 nkxx188，采用 MIT License；其 MIT 文本和版权声明保留在 LICENSES/MIT-ComfyUI-MiniMaxH3-Easy.txt。上游项目要求对实质性复用或改编保留作者与项目署名；本仓库已在节点头部、README、NOTICE 和 Release 中明确保留该声明。
节点的 API 服务配置、模型发现和提示词优化实现借鉴自 yawiii/ComfyUI-Prompt-Assistant，原作者为 yawiii，采用 GNU GPL v3。由于本仓库包含该来源的改编内容，整个仓库按 GNU GPL v3 发布。
“完整低显存分块（实验）”包含来自 matlowai/ComfyUI-MAINodes 的 H3 Streamed Blocks 衍生实现，版权归 MATLOWAI，采用 GPL-3.0-or-later。保留的源文件、完整许可证与改动说明见 NOTICE、third_party/mainodes_h3_streamed_blocks.py 和 LICENSES/GPL-3.0-or-later-ComfyUI-MAINodes.txt。
FeiHou 的改动包括：固定 9 图 / 3 视频 / 3 音频的内嵌媒体面板、上传与工作流持久化、FeiHou LoRA Stack 接入、ComfyUI 设置页内的 API 与提示词规则管理、服务/模型选择、运行时提示词扩写/反推、提示词预览输出，以及独立的 RefMod 接口。普通素材的 conditioning 遵循 ComfyUI 官方 MiniMax H3 Reference to Video 行为；内嵌面板的数量限制不包括外部 RefMod。