MiniMax H3 官方文档调研

调研时间: 2026-08-04 · 来源: HuggingFace MiniMaxAI/MiniMax-H3 官方 README + Prompt Writing Guide + License
模型发布日期: 2026-08-02 · 1418 likes (HF)

一、系统总览

MiniMax H3 是一个 全能多模态生成系统 (Omni-Modal Generative System)，支持文本/图像/视频/音频的统一理解，可生成带原生立体声音频的视频。

规格	参数
输出时长	4–15 秒
宽高比	21:9, 16:9, 4:3, 1:1, 3:4, 9:16 等广泛支持
输出分辨率	短边默认 768px；2K 需通过 H3-Regenerate-2K
帧率	24 FPS
输出音频	32 kHz 立体声 (stereo)
支持对话语言	11种稳定支持：阿拉伯语/中文/英语/法语/德语/意大利语/日语/韩语/葡萄牙语/俄语/西班牙语

二、三大模块架构

完整 H3 系统由三个模块组成：

1️⃣ H3-Context-IR 未开源

多模态指令预处理系统。接收自由格式输入（文本+图+视频+音频），通过多阶段工作流（指令解析→跨模态关联→时序理解→复杂逻辑推理），将其序列化为 H3-Base 能理解的 Context Intermediate Representation。

官方强调：H3-Context-IR 对最终输出质量至关重要，强烈建议将其集成到生成管线中，或按照 Prompting Guidance 自建等价系统。

⚠️ 因为依赖多阶段工作流和多个托管模型/服务，未包含在本次开源中。提供 API 调用和详细教程。

2️⃣ H3-Base 已开源

核心生成模型。接收 Context-IR 输出，生成 768p 分辨率的视频+音频。

架构细节

H3-Encoder：使用 Qwen3-VL-32B 全量预训练权重，取第 50 层 hidden states → 注入特殊 token（如 <d>）
H3-VisualVAE：时间因果视频自编码器，空间压缩 16× / 时间压缩 4× / 24 latent 通道 (f16t4d24)；patch size 1×2×2 → 有效空间下采样 32×
H3-AudioVAE：左右声道独立处理 → 重组为立体声；32kHz 音频压缩为 40Hz latent 序列
H3-Omni-Transformer：33B 参数稠密单流 Transformer（其中 ~13B 在 AdaLN 分支，推理时可跳过）；三维 MM-RoPE 位置编码；原生稀疏注意力（首版仅提供 full attention，稀疏版未来发布）

模型是 CFG-distilled（CFG 蒸馏），推理时 CFG 可设为低值或 1.0。

3️⃣ H3-Regenerate-2K 未开源

2K 分辨率再生模块。不是传统超分，而是将 768p 结果 + 原始 context 重新输入 H3，以 in-context 方式再生 2K 输出。

优势：① 复用 H3 base 模型的生成能力 ② in-context 格式可复用原始多模态信息（恢复小文字/细节等传统超分需要"猜"的信息）。

⚠️ 系统复杂，尚未开源。提供 API 验证。

三、模型变体与输入规格

变体	输入模式	规格
H3-Base-FL2VA `fl2va`	首尾帧模式 (First-and-Last-Frame)	支持 0/1/2 张输入图： • 无图 = T2V • 1张 = 首帧→视频或尾帧→视频 • 2张 = 首尾帧→视频
H3-Base-Ref2VA `ref2va`	全参考模式 (Omni-Reference)	多模态参考输入： • 图片 ≤ 9 张 • 视频 ≤ 3 个（每个 2–15s，总时长 ≤15s） • 音频 ≤ 3 个（须配合图/视频使用，不能单独输入；每个 2–15s，总时长 ≤15s） • 混合输入：文件总数 ≤ 12

📐 分辨率说明

• 短边默认 768px

• ComfyUI 量化版支持到 768×1344（竖屏上限）

• 2K 需要通过 H3-Regenerate-2K（API only，未开源）

• 时长：duration 对齐 17 帧每块（17k+5 网格 @24fps）

四、部署方式

框架	链接	说明
SGLang	cookbook	官方首选，支持 Ulysses 并行
vLLM	recipes	支持 H3 推理
diffusers	docs	ModularPipeline.from_pretrained 自动拉取
ComfyUI	tutorial	≥ v0.30.0 原生节点支持

SGLang 部署示例

# FL2VA (T2V/I2V)
sglang serve \
  --model-path MiniMaxAI/MiniMax-H3 \
  --num-gpus 4 \
  --ulysses-degree 4 \
  --performance-mode speed \
  --host 0.0.0.0 --port 30010 \
  --model-variant fl2va

# Ref2VA (R2V)
sglang serve \
  --model-path MiniMaxAI/MiniMax-H3 \
  --num-gpus 4 \
  --ulysses-degree 4 \
  --performance-mode speed \
  --host 0.0.0.0 --port 30011 \
  --model-variant ref2va

🔑 官方推荐采样参数

参数	推荐值	说明
steps	50	标准质量（low profile ~17 步等效）
flow_shift (video)	12.0	⚠️ 不要手动降低！否则水流波动
audio_flow_shift	3.0	音频噪声调度偏移
CFG	低/1.0	模型已 CFG-distilled
sampler	euler
scheduler	simple / beta	ref 多时 beta 更优

Quality Profile（4×H200 参考）

Quality	等效步数	延迟	SSIM
lossless	50	75s	1.000
high	~36	54s	0.931
medium	~20	30s	0.818
low	~17	26s	0.794

ComfyUI 量化文件清单

📂 ComfyUI/models/
├── 📂 diffusion_models/
│   ├── minimax_h3_fl2va_bf16.safetensors          61.7 GB  (全精度)
│   ├── minimax_h3_fl2va_int8_convrot.safetensors  31.7 GB  (int8)
│   ├── minimax_h3_fl2va_pruned_int8_convrot       19.5 GB  (int8 剪枝 ★推荐)
│   ├── minimax_h3_fl2va_pruned_fp8_scaled          —       (fp8 剪枝)
│   ├── minimax_h3_ref2va_*  (同上 4 个量化变体)
├── 📂 text_encoders/
│   ├── qwen3vl_32b_minimax_h3_bf16                48.0 GB
│   ├── qwen3vl_32b_minimax_h3_int8_convrot        25.3 GB
│   └── qwen3vl_32b_minimax_h3_nvfp4_awq           14.6 GB  (★推荐)
├── 📂 vae/
│   ├── minimax_h3_video_vae_fp16                   4.9 GB
│   └── minimax_h3_audio_vae_fp32                   0.6 GB

五、Prompt 编写指南（核心）

这是官方文档中最有价值的部分——H3 的 prompt 不是自由文本，而是结构化格式。

5.1 最终 Prompt 结构

由两部分组成：指令行 + 三个核心字段

指令行（按模式不同）

模式	指令行
T2VA	无指令行，直接开始核心字段
I2VA	`For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced.`
FL2VA	`How the reference pictures align with the target video — Picture 1 (from Shot 1) aligns with the 0.00-second mark of the target video; Picture 2 (from Shot N) aligns with the S.SS-second mark of the target video.`
L2VA	`How the reference pictures align with the target video — <Picture 1> (from [Shot N]) aligns with the S.SS-second mark of the target video.`

三个核心字段

integrated_multimodal_description

主描述体。沿时间轴描述视觉、动作、镜头切换、说话者、对话、歌唱和场景内声音。

overall_soundscape

环境音摘要（1-4句）。风声/雨声/交通/脚步声/布料声/撞击声/呼吸/笑声。对话和音乐不写这里。

non_diegetic_music

非叙事音乐（1-3句）。角色听不到、只有观众能听到的 BGM。描述乐器/速度/节奏/动态变化。

5.2 镜头与剪辑

第一个镜头 [Shot 1] 不加时间戳
后续镜头用严格递增的切换时间：[Shot 2] At 00:03.500, the camera cuts to...
普通切换用 the camera cuts to / the shot transitions to
只有用户明确要求时才用 cross-dissolve / fade / wipe

5.3 运镜表达（三维度）

维度	可用表达	说明
运动类型	`Zoom In / Zoom Out`	焦距变化，机身不动
	`Push In / Pull Out`	机身前进/后退
	`Pan Left / Pan Right`	镜头水平旋转
	`Truck Left / Truck Right`	机身水平平移
	`Tilt Up / Tilt Down`	镜头垂直旋转
	`Pedestal Up / Pedestal Down`	整机上升/下降
	`Arc Shot`	弧线运动围绕主体
	`Tracking Shot`	跟随运动主体
	`Static Shot`	完全静止
	`Shake Slightly / Shake Strongly`	轻微/强烈抖动
	`POV / Roll CW / Roll CCW`	主观视角 / 滚转
幅度	`with small amplitude` / `with large amplitude`	中等通常省略
速度	`at slow speed` / `at fast speed`	正常速度通常省略

5.4 对话格式

说话者用稳定 ID：(S1), (S2)；多人同说用 (S1,S2)
首次出现时描述角色身份（年龄/性别/音色/语速/口音）
对话内容用 <d> 包裹：The woman (S1) says, <d>[English] I get off at the next station.</d>
画外音用 says in an off-screen voiceover，且必须声明 his/her lips remain completely closed
跨镜头对话用 <scenetrans> 标记连续性
被截断用 <cutoff>

5.5 完整 T2VA 示例

integrated_multimodal_description: [Shot 1] Live-action, cinematic, a medium-wide shot 
frames a baker opening the shutters of a small street bakery before sunrise. The camera 
pushes in with small amplitude at slow speed as the middle-aged baker with a calm, 
slightly raspy voice (S1) places a fresh loaf on the wooden counter and says: 
<d>[English] First batch of the morning.</d> 
[Shot 2] At 00:05.000, the camera cuts to a close-up of steam rising from the sliced 
bread while the baker's final words carry over from the previous shot.

overall_soundscape: Wooden shutters scrape open over a quiet street as trays clink 
softly inside the bakery. The doorbell rings once, followed by light footsteps and 
the crisp sound of bread being sliced.

non_diegetic_music: A soft acoustic-guitar pattern at a moderate tempo, joined by 
sparse upright-bass notes and a gentle fade at the end.

六、Ref2VA 全参考模式（6 节结构）

Ref2VA 的 prompt 比基础模式复杂得多，由六个结构化段落组成：

段落	用途
`subject_definitions`	定义引用内容及其参考标签
`summary`	用方括号任务类型前缀概述（如 `[video editing + audio reuse]`）
`retention_analysis`	描述引用内容的保留/转移/复用程度
`detailed_description`	按播放顺序逐镜头描述（主描述体，350-500词）
`overall_soundscape`	环境音摘要
`non_diegetic_music`	非叙事音乐

四种参考标签

标签	含义
`<Subject N>`	可复用的可见内容（人/动物/物体/场景/服装/风格/动作）
`<Picture N>`	作为具体帧/锚点的参考图
`<Video N>`	编辑源视频/续拍起点/整体时序参考
`<Audio N>`	音频信号（复制或参考用）

六种任务类型

任务类型	适用场景
`keyframe completion`	图片作为目标视频的首帧/关键帧/尾帧
`reference generation`	图/视频/音频提供生成指导（角色/场景/风格/动作）
`video editing`	直接修改已有视频
`video continuation`	从已有视频延续/扩展
`audio reuse`	音频信号完整或部分复用
`audio reference`	仅参考音色/节奏/风格（不直接复制）

七、许可证要点

⚠️ MiniMax H3 Community License 关键限制

条款	详情
排除地区	❌ 欧盟 / 英国 / 韩国 / 美国 ✅ 其他地区可用（含中国）
商业使用	年收入 >2000万美元需单独授权（联系 api@minimax.io）
再分发	须附带 License 副本 + NOTICE 文件
衍生品限制	不能用输出改进其他 AI 模型（H3 自身衍生品除外）
标注义务	鼓励标注 "Powered by MiniMax H3" + AI 生成标识
管辖法	中国香港特别行政区法律
Text Encoder	Qwen3-VL-32B → Apache 2.0（兼容）

八、对我们管线的启示

✅ 新发现 / 有价值的点

H3-Context-IR 是关键中间层：官方明确说它"对最终输出质量至关重要"。我们目前直接把 prompt 送入 H3-Base，跳过了 Context-IR。可以考虑自建简化版 context 处理器，或调用官方 API。
结构化 prompt 格式：H3 的 prompt 不是自由文本，而是 integrated_multimodal_description + overall_soundscape + non_diegetic_music 三字段格式。我们的 prompt 编写应该遵循这个结构。
对话标记 <d>：H3 用 <d>[Language] text</d> 标记对话。这直接影响音频生成中的对话同步。我们的 TTS 对白 + 视频生成的集成可以参考。
2K 再生思路：in-context regeneration 而非传统超分。思路新颖，未来开源后值得集成。
SGLang 是官方首选推理框架：我们目前用 ComfyUI（量化版），SGLang 在多 GPU 场景可能更优。
Ref2VA 6 节结构：比 FL2VA 复杂得多，有 subject_definitions / retention_analysis 等结构化段落。如果要用 R2V 做角色锁定，需要严格按格式编写。

⚠️ 注意事项

排除地区：EU/UK/KR/US 不可用。我们的部署在中国境内不受影响，但产品出海需注意。
Context-IR 和 Regenerate-2K 均未开源：开源的只是 H3-Base（768p），官方 API 才有完整管线。
33B 参数 Transformer：即使 AdaLN 跳过后 ~20B 有效参数，3090 仍需 Dynamic VRAM。官方推荐 4×H200。
稀疏注意力未发布：首版只有 full attention，长序列计算成本高。未来版本可能有显著提速。

— 调研完毕 · 数据来源: MiniMaxAI/MiniMax-H3 HuggingFace 官方文档 —

🎬 MiniMax H3 官方文档调研