MiniMax-H3-Longvideos API 参考：H3 Long Videos 节点全部输入输出端口与参数速查-平芜编程栈

人工智能
AI 应用
媒体生成

【免费下载链接】MiniMax-H3-Longvideos

项目地址：https://ai.gitcode.com/hf_mirrors/Smite79/MiniMax-H3-Longvideos

本文是MiniMax-H3-Longvideos（一个 ComfyUI 自定义节点包）的完整 API 速查：它能把一段文字提示词转换成MiniMax-H3 长视频 + 同步音频（单镜头约 15 秒，链式拼接可达约 120 秒）。文章逐一列出H3 Long Videos主节点及其附带 3 个工具节点的全部输入端口、输出端口与参数默认值，适合新手接线排错、也方便老手快速查参数，无需再翻源码。

📦 这个包提供哪 4 个节点？

MiniMax-H3-Longvideos 安装后在 ComfyUI 中注册 4 个节点，入口定义见init.py：

节点显示名	类名 / 注册键	分类	源码文件
H3 Long Videos	`H3LongVideos`	sampling/minimax	sampler.py
H3 Shot Length	`H3ShotLength`	MiniMax-H3/utils	shot_length.py
H3 Model Inspector	`H3ModelInspector`	MiniMax-H3/multishot	inspector.py
H3 Overlay	`H3Overlay`	MiniMax-H3/utils	overlay.py

💡 注意：采样器在 sampler.py 只以H3LongVideos一个键注册，但init.py 提到旧工作流使用的H3LongVideosFL2VA、H3LongVideosV1、H3LongVideosREF2VA名称均指向同一类，老工作流可正常加载。

🔌 节点一：H3 Long Videos（核心采样节点）

输入输出声明位于 sampler.py，共10 个必需输入 + 30 个可选输入 + 8 个输出。

必需输入端口（Required Inputs）

端口	类型	说明
`model`	MODEL	MiniMax-H3 UNET（fl2va/ref2va 混合模型效果最佳）
`clip`	CLIP	H3 文本编码器，loader 类型选`minimax`
`vae`	VAE	H3视频VAE
`audio_vae`	VAE	H3音频VAE（必须是转换后的版本）
`prompt`	STRING（多行，强制输入）	第一段 = 场景（拼接到每个镜头），其后每段 = 一个镜头
`resolution`	下拉	`16:9 / 9:16 / 4:3 / 3:4 / 1:1 / 21:9 / 9:21`，默认`16:9`，决定宽高比
`megapixels`	FLOAT 0–2	默认`1.0`（H3 原生 1 MP 预算）；设`0`直接使用预设尺寸
`shot_seconds`	FLOAT 1–15	默认`10`，每个镜头的时长上限
`steps`	INT 1–100	默认`8`；配 turbo/distill LoRA 用 6–8，否则 20+
`cfg`	FLOAT 1–20	固定`1.0`——H3 是 CFG-free，负提示词不会被评估
`sampler_name`	下拉	默认`res_multistep`（或配合 PDD Acc 用`euler`）
`scheduler`	下拉	默认`simple`
`seed`	INT	支持"生成后控制"；整条链共用一个种子

可选输入端口（Optional Inputs）

图像 / 条件类端口

端口	类型	说明
`first_frame`	IMAGE	钉住第 1 镜的首帧（注意它会锁定整个构图，人物定妆照请走`ref_image_1`）
`ref_image_1`~`ref_image_4`	IMAGE	身份参考图；提示词里用`<Picture N>`标签可指定跟随哪个人/物
`negative`	CONDITIONING	cfg=1.0 时被忽略，仅为接口完整
`sigmas`	SIGMAS	外部采样计划（如 PDD Acc 的 Apply 节点输出）
`ambient_audio`	AUDIO	环境音床覆盖输入；留空则由场景自动合成

数值 / 布尔开关类（悬停均有 tooltip 说明）

端口	默认值	范围	作用一句话
`shift_video`	12.0	1–20	视频流 flow shift
`shift_audio`	3.0	1–20	音频流 flow shift，与视频保持约 4:1
`apply_model_sampling`	True	布尔	节点内部修补双 schedule 开关
`silence_nonspeech`	True	布尔	无台词镜头把音频分支锚定到真实静音
`trim_seam`	True	布尔	去掉后续镜头首帧（它是关键帧的重复）
`ref_noise_aug`	0.999	0.5–1.0	参考图"干净度"，调低可防背景/姿势被复刻
`tiled_decode`	True	布尔	分块解码，防显存溢出
`cleanup_between_shots`	True	布尔	镜头之间清理显存
`latent_upscale`	off	下拉	latent 空间放大（需另装 Upscaler 包）
`latent_upscale_scale`	2.0	1–4	latent 放大倍率
`upscale`	off	off/rtx/model/lanczos	成片后的帧级放大后处理
`upscale_model`	none	下拉	`upscale=model`时从 upscale_models 选择
`upscale_target_short_edge`	0	0–4096	成片短边像素目标，0 保持模型倍率
`upscale_batch`	4	1–64	模型放大的每批帧数
`shot_length`	from the beat	二选一	`from the beat`按台词内容自适应镜头时长；`fixed`统一为`shot_seconds`
`auto_remove`	True	布尔	从台词自动识别"脱衣"动作并同步更新角色状态
`restart_after_removal`	True	布尔	脱衣镜头后，下一镜从头生成而非继承末帧
`hold_restraints`	True	布尔	束缚道具一旦戴上，后续每镜持续描述保持
`plan_only`	False	布尔	⭐ 只报告镜头切分、时长与警告，不渲染，建议每次先跑一遍
`anchor`	空	STRING 多行	全局镜头框架；填写后提示词所有段落都视为 beat
`character_memory`	空	STRING 多行	角色卡（`名字: 特征`每行一人），复印到每个镜头保持服装一致
`character_guard`	True	布尔	每镜只描述该 beat 涉及的人物
`pace`	1.0	0.25–2.0	beat 时长缩放，<1 加快、>1 放慢（仅`from the beat`生效）
`auto_sound`	True	布尔	为动作镜头生成动作音效
`hold_scene_state`	True	布尔	门/窗等"已描述状态"固定在首帧
`mouths_shut_when_no_line`	True	布尔	无台词镜头闭嘴（代价：放弃该镜手写的环境音）
`hold_gaze`	True	布尔	让眼神落在台词指定的注视对象上
`ambient_level`	0.25	0–1	环境音床响度；0 关闭，0.15–0.3 为宜
`foley_level`	0.35	0–1	无台词镜头的动作拟音合成音量

输出端口（8 个）

RETURN 定义见 sampler.py：

输出	类型	用途
`images`	IMAGE	成片帧序列 → 接 Video Combine / Save Video
`audio`	AUDIO	同步音轨
`info`	STRING	节点做了什么 + 全部警告，出问题时必读
`script`	STRING	实际逐镜头发送给模型的文本
`frames_per_shot`	INT	每镜帧数
`total_frames`	INT	总帧数
`shots`	INT	镜头总数
`video_seconds`	FLOAT	视频总时长（秒）

最小接线示意（来自 README.md）：

UNETLoader ─┐ images ─> Video Combine / Save Video CLIPLoader ─┼─> H3 Long Videos ─> audio ─┘ VAELoader ──┘ info ─> Show Text

🎞 节点二：H3 Shot Length（秒 ↔ 帧换算）

声明见 shot_length.py。H3 帧数必须落在17k+5网格上且 ≤ 362 帧（约 15 秒），该节点把"秒"换算成合法帧数，一次输入同时喂给采样器和预览节点。

方向	端口	类型	默认值
输入	`shot_seconds`	FLOAT 0.2–15.1	5.0
输入	`fps`	INT 1–60	24
输入（可选）	`cap_to_h3_max`	BOOLEAN	True（钳制到 362 帧）
输出	`seconds`	FLOAT	→ 采样器`shot_seconds`
输出	`frames`	INT	→ Model Preview Override
输出	`info`	STRING	换算说明文本

🔍 节点三：H3 Model Inspector（精度体检）

声明见 inspector.py。输入只需一个model（MODEL），输出：

format（STRING）：主导精度标签，如BF16 / FP8 (e4m3) / NVFP4 / MXFP8 / INT8 convrot / W4A8等
report（STRING）：逐格式图层统计 + 你的显卡是否原生支持 NVFP4 / MXFP8 计算（该节点OUTPUT_NODE=True，会直接把报告渲染在画布上）

✍️ 节点四：H3 Overlay（水印 + 片头字幕）

声明见 overlay.py。它是纯合成节点，应放在所有放大处理之后。

方向	端口	默认值	说明
输入	`images`	—	成品帧
输入	`fps`	24	仅用于把片头秒数换算成帧，需与保存节点一致
输入（可选）	`watermark_text`	空	水印文字，空 = 关闭
输入（可选）	`watermark_position`	bottom-right	7 个位置可选
输入（可选）	`watermark_size`/`opacity`/`margin`	4.0 / 0.75 / 3.0	字号（短边百分比）/ 不透明度 / 边距
输入（可选）	`intro_text`	空	片头标题文字，空 = 关闭
输入（可选）	`intro_position`/`intro_seconds`/`intro_fade`	center / 3.0 / 0.6	位置、保持时长、淡出时长
输入（可选）	`intro_size`/`overlay_font`/`overlay_stroke`	9.0 / arial.ttf / 0	片头字号、字体、描边粗细
输出	`images`	—	叠加后的帧
输出	`info`	—	执行备注（如跳过原因）

✅ 推荐起步参数与常用资料

新手最省心的组合：cfg=1.0、sampler_name=res_multistep、scheduler=simple、shift_video=12 / shift_audio=3、megapixels=1.0，然后先开plan_only跑一遍，读info确认镜头切分无误再正式渲染。
提示词写法（一段 = 一镜，对话用双引号）详见 README.md，提示词解析引擎在 engine.py、镜头拆分逻辑在 sampler.py。
现成演示工作流：workflows/H3 LongVideos Demo Workflow.json，导入即可对照本文各端口位置。
安装方式：把整个文件夹拷入ComfyUI/custom_nodes/后重启 ComfyUI服务器（需 ComfyUI 0.31+）。