用官方 API 还是本地部署 H3：按你的实际处境倒推
很多人打开 MiniMax H3 的仓库，第一反应是「权重开源了，那我本地跑就行」。这个推理在 H3 上不成立，而且不成立的原因不是显存、不是速度，是系统结构——H3 从设计上就不是一个模型，而是三个模块串起来的系统，开源发布的只有中间那一块。
所以「用 API 还是本地部署」这个问题，在 H3 这里并不是同一件事的两种做法，它俩能做的事本来就不一样。下面按截至 2026-08-09 的官方仓库 README 口径，把这条选型路径走一遍。
一、先把结构摆出来，选型的答案基本写在这张表里
README 的 System Overview 把 MiniMax H3 拆成三块：
| 模块 | 职责 | 开源状态 |
|---|---|---|
| H3-Context-IR | 深度理解并精炼输入的多模态指令，转成 Context Intermediate Representation（上下文中间表示）再交给生成 | 未包含在本次开源发布中，提供 API |
| H3-Base | 基于 Context-IR 的输出生成音频与视频，产出 768p 结果 | 已开源，两个 checkpoint |
| H3-Regenerate-2K | 把 768p 结果连同原始上下文送回 H3，重新生成 2K 输出 | 尚未开源，README 写「Due to the complexity of the system, this module is not yet open-sourced. We will release it once it is ready.」，提供 API 用于验证官方结果 |
看清楚这三行，选型就已经完成了一大半：
拿到开源权重 ≠ 拿到官方效果。 前面的上下文理解和后面的 2K 重生成都不在开源包里。本地部署 H3-Base，能力边界就是 768p，这不是调参能突破的，是模块本身没发布。
README 里还有一句必须原样带出来的强调：「H3-Context-IR is critical to the quality of the final output, so we strongly recommend incorporating it into your generation pipeline or following the “Prompting Guidance” to build your own context-processing system.」——官方自己明说 Context-IR 对最终输出质量至关重要，要么接进来，要么照 Prompting Guidance 自建一套上下文处理系统。
这句话的分量在于：它不是「建议你顺便用一下」，而是把这一层定义成了质量的关键路径。而这一层没有开源。
顺带把能力盒子的边界也列一下，很多需求在这一步就该被筛掉：输出时长 4–15 秒，帧率 24 FPS，音频 32 kHz 立体声，宽高比支持 21:9、16:9、4:3、1:1、3:4、9:16 等较宽范围，短边默认 768 像素，对白稳定支持 11 种语言（阿拉伯语、中文、英语、法语、德语、意大利语、日语、韩语、葡萄牙语、俄语、西班牙语），其它语言有不同程度支持。如果你要的是三分钟长片，这套系统从规格上就不接。
二、第一个岔路口：你要的成品是 768p 还是 2K
这是最干脆的一刀。
- 只要 768p：本地部署 H3-Base 是完整可行的路径。README 把它单列为一条官方验证路径「Local Deployment of H3-Base」，验证 768p 输出。仓库
scripts/readme/下提供了reproducible-768p-t2va-request.sh、reproducible-768p-fl2va-request.sh、reproducible-768p-ref2va-request.sh三个可复现脚本（脚本正文本文没有读取，不做描述）。 - 要 2K：本地这条路目前走不通。2K 生成需要通过 H3-Regenerate-2K 实现，而该模块尚未开源。要么直接调官方开放平台 API，要么走下面第五节的混合路线。
别在这一步跟自己较劲。分辨率上限是发布状态决定的，不是配置问题。
三、第二个岔路口：你的输入有多复杂
如果你的输入就是一句话文生视频，自己写提示词和走 Context-IR 之间的差距相对可控；输入越复杂，Context-IR 承担的活越重。
README 的 Full 2K Workflow 里给了三个 case 的 Context-IR 返回，其中 usage 字段可以直接说明这个量级差异：
| case | 类型 | duration | total_tokens | prompt_tokens | completion_tokens |
|---|---|---|---|---|---|
| T2VA | 文生视频 | 10 秒 | 8565 | 5650 | 2915 |
| I2VA | 首帧图生视频 | 8 秒 | 22822 | 12800 | 10022 |
| Ref2VA | 视频+音频多模态参考 | 5 秒 | 39299 | 33323 | 5976 |
这是官方 README 三个示例的用量，仅供理解量级，不是价格也不是配额。
反直觉的地方在这儿：时长最短的 Ref2VA（5 秒）token 消耗最高，因为参考素材本身要进上下文；纯文本的 10 秒 T2VA 反而最低。也就是说，「视频短所以简单」这个直觉在 H3 的上下文处理阶段是反的。
那不接 API 行不行？官方给的替代路径是照 Prompting Guidance 自建。仓库带了九个 skill，其中 h3-prompt-writing 就是提示词写作指南，安装命令 README 原样给的是：
npx skills add https://github.com/MiniMax-AI/MiniMax-H3 --skill h3-prompt-writing
它附两份指南：references/base-en.txt（文本/关键帧模式）与 references/ref-en.txt（全参考 Ref2VA 模式）。规则相当具体——五种输入模式（T2VA / I2VA / FL2VA / L2VA / Ref2VA）、三个必须保留字段名的核心字段（integrated_multimodal_description、overall_soundscape、non_diegetic_music）、对白用 <d> 包裹且里面只放语言标签与原样台词、跨切点续音用 <scenetrans>、被结尾截断用 <cutoff>、全参考模式的四类标签 <Subject N> / <Picture N> / <Video N> / <Audio N> 并要求在六个章节里含义保持一致。
这套东西确实能让你自己产出结构化提示词。但要把话说到位：官方 README 把它定位为替代路径，不等于自建系统能得到与官方 API 相同的结果。 Context-IR 本身没开源，我们没有任何两条路的对比数据，也不会去猜。
所以这个岔路口的判断依据是：输入越接近纯文本、你越愿意亲手按 skill 规则打磨提示词，自建路线的落差就越小；输入是多张参考图、多段视频加音频的混合素材（Ref2VA 允许图像 ≤ 9 张、视频 ≤ 3 段、音频 ≤ 3 段、所有类型合计 ≤ 12 个文件，视频与音频每段 2–15 秒、总时长 ≤ 15 秒，音频不能作为唯一输入），自己搭一套等效的上下文处理就是另一个量级的工程量。
四、第三个岔路口：数据能不能出本地，以及审核算加分还是减分
README 的 Safety Guardrails 写得很直白：用户提交的文本、图像与视频，以及增强后的提示词，都要经过自动审核；疑似违法、色情或侵犯第三方权利的内容可能被拦截。官方同时承认，使用的是行业标准过滤措施，但无法消除误判（false positives）与漏判（false negatives）。另外还写明，这些护栏不影响被许可方在 MiniMax H3 Community License 下的义务，尤其是与合法使用和使用限制相关的义务。
这段对选型的意义是双向的：
- 如果你的素材涉及不能外发的内容，那么「Context-IR 走官方 API 就会过审核」这一条本身就是一个约束——因为增强后的提示词也在审核范围内。
- 如果你反过来希望平台侧有一层内容过滤兜底，那这是本地部署给不了的，本地 H3-Base 不带这层。
- 但无论走哪条，官方明说护栏不免除许可义务。许可条款以官方 LICENSE 原文为准（License 全称是 MiniMax H3 Community License Agreement，原文在
huggingface.co/MiniMaxAI/MiniMax-H3/blob/main/LICENSE），本文不做任何商用边界、二次分发或产出物权属的解读。
五、第四个岔路口：命令行与多卡环境
本地部署这条路是有门槛的，门槛在工程侧而不在按钮上。
README 推荐了四个推理框架：SGLang（docs.sglang.io，cookbook 路径 /cookbook/diffusion/MiniMax/MiniMax-H3）、vLLM（recipes 路径 recipes.vllm.ai/MiniMaxAI/MiniMax-H3）、diffusers（文档在 minimax-h3 分支的 docs/source/en/api/pipelines/minimax_h3.md）、ComfyUI（教程 docs.comfy.org/tutorials/video/minimax/minimax-h3）。
几条能直接省事的判断依据：
权重别无脑全量下。 仓库把原始 checkpoint（FL2VA/、Ref2VA/）与 diffusers 格式并排托管，不加 --include 会把两套都拉下来，tokenizer 相关文件在两套格式里是重复出现的。README 原样命令：
# Original checkpoint, both task families (SGLang, vLLM):
hf download MiniMaxAI/MiniMax-H3 --include "model_index.json" "FL2VA/*" "Ref2VA/*" --local-dir MiniMax-H3
# Or a single task family:
hf download MiniMaxAI/MiniMax-H3 --include "model_index.json" "FL2VA/*" --local-dir MiniMax-H3
只做文生视频和首尾帧的人，只下 FL2VA/* 就够；只跑 diffusers 的人根本不需要手动下载——README 说 ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3") 会精确拉取所需组件。
diffusers 版本是个坑。 仓库 requirements.txt 的官方注释写明，官方文档引用的是 diffusers 的 minimax-h3 分支，在它进 PyPI 之前，给的安装方式是 pip install "git+https://github.com/huggingface/diffusers.git@minimax-h3"。直接装 PyPI 版本可能没有 H3 的模型类。
两个变体是两个服务。 SGLang 部署命令 README 原样如下（FL2VA）：
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 那条只差 --port 30011 与 --model-variant ref2va。也就是说，想同时提供 t2va/fl2va 与 ref2va 两类能力，就是两个服务实例、两个端口。官方示例使用 4 GPU 配置，--num-gpus 与 --ulysses-degree 在示例里同为 4；README 没有说这是最低要求，所以本文不会写成「需要 4 张卡」，--ulysses-degree 与 --performance-mode speed 的含义也不在我们有依据的范围内，不展开。
如果这几行命令看着让你发怵，那本地部署这条路的真实成本会比你预期的高——它不是装个软件的事。
六、第五个岔路口：先看效果，还是要接进服务
只是想先看看这套系统能干什么，README 给了现成入口：
| 形态 | 全球 | 中国 |
|---|---|---|
| API 平台 | platform.minimax.io | platform.minimaxi.com |
| WebApp | hailuoai.video（/tools/minimax-h3） | hailuoai.com |
| 桌面版 | hub.minimax.io | hub.minimaxi.com |
API 文档路径是 /docs/api-reference/video-generation-v2-create。社区在 Discord（discord.com/invite/dbMxutw7tP），微信联系入口在 platform.minimaxi.com/docs/faq/contact-us，仓库联系邮箱是 model@minimax.io。
至于贵不贵、够不够用——我们没有任何定价、免费额度或速率限制的事实，本文一个数字都不写，请直接看官方平台页。
七、其实还有第三个答案：Full 2K Workflow
README 给的两条验证路径里，第一条就是把两边拼起来：本地部署的 H3-Base 负责生成，官方的 H3-Context-IR 与 H3-Regenerate-2K 走 API，端到端复现 2K 输出质量。
开始前配置的变量，README 原样是：
# URL of your SGLang deployment
SGLANG_DEPLOYMENT_URL="<sglang-deployment-url>"
# MiniMax API endpoint (choose one)
# CN
MINIMAX_API_BASE="https://api.minimaxi.com"
# Global
# MINIMAX_API_BASE="https://api.minimax.io"
# API token obtained from the MiniMax platform
TOKEN="<token>"
涉及的三个端点：
| 用途 | 端点 |
|---|---|
| 创建 H3-2K | /video-generation-v2-create |
| H3-Context-IR | /video-generation-v2-h3-context-ir |
| H3-Regenerate-2K | /video-generation-v2-regeneration |
有一个工程细节值得记住：README 的示例把本地 H3-Base 的输出文件编码成 Base64 Data URL，但生产场景官方推荐把视频上传到公开可访问的 URL，把该 URL 作为 base_video 传入。三个 case 各自对应的 .sh 脚本都在 scripts/readme/ 下，脚本正文本文没有读取，不做描述。
这条路的性质要说清楚：它仍然依赖联网和 token，只是把最重的生成环节放在了自己机器上。它不解决「数据完全不出本地」的诉求。
八、这几个维度本文不比
选型文章最容易翻车的地方是拿没有依据的东西下结论，这里明确列出来：
- 速度、显存、模型体积：官方 README 没有给这类数据，我们也没有部署过，不比。
- 画质好坏、与其它视频生成模型的效果对比：没有官方跑分，没有第三方评测，不比。
- 价格、额度、速率限制：一个数字都没有，不比。
- ComfyUI 侧与官方权重的效果差异：MiniMax README 写明发布的 checkpoint 精度是 BF16，而在别的框架里跑到的权重形态未必是同一套，两边不要混着评估；具体差异我们没有任何数据，不给结论。
--ulysses-degree改成别的值会怎样：没有事实来源，不猜。
九、条件式结论
不给「推荐用 X」这种断言，给条件：
- 成品必须是 2K → 本地部署单独走不通，走官方 API，或者走 Full 2K Workflow 混合方案。
- 768p 够用，且不希望素材外发 → 本地部署 H3-Base，配合按
h3-prompt-writingskill 自建的提示词流程。但要接受一点：官方明说 Context-IR 对最终质量至关重要，自建是替代路径而非等价替换。 - 输入是复杂的多模态参考（多图 + 多段视频 + 音频） → Context-IR 承担的工作量最大（README 示例里 Ref2VA 的 token 用量也最高），自建的落差风险相应最大，接官方 Context-IR 更省心。
- 只想先确认这套系统适不适合你的场景 → 先用 WebApp 或桌面版入口，别一上来就下权重。
- 团队里没人熟悉命令行部署与多卡服务 → 本地路线的真实成本会显著高于预期，先走 API 把需求验证清楚再说。
- 既要 2K 又要素材完全不出本地 → 截至 2026-08-09 的仓库状态，这个组合暂时没有官方路径；Regenerate-2K 未开源，README 只写了「We will release it once it is ready」，没有给时间表。等待，或者降级到 768p。
最后提醒一句：以上全部基于 2026-08-09 的仓库快照。H3 的模块开放状态是会变的——Regenerate-2K 一旦开源，第一个岔路口的答案就会整个翻过来。做长期方案时，把「模块开放状态」当成一个会变的输入，而不是常量。
延伸阅读
- 本地部署 H3-Base 的完整路径：从下载范围到 SGLang 起服务
- MiniMax H3 的 Full 2K Workflow：本地 SGLang 服务 + 官方 API 怎么串成一条链
- SGLang / vLLM / diffusers / ComfyUI：H3 四种跑法怎么选
本文依据 MiniMax H3 官方仓库（github.com/MiniMax-AI/MiniMax-H3）的 README、模型配置文件与官方 h3-prompt-writing skill 文档整理，核对日 2026-08-09。本文内容为官方仓库口径，未在本机部署或调用过 H3。模型、部署方式与许可条款以官方最新说明为准。许可条款请以官方 LICENSE 原文为准，本文不构成法律意见。