MiniMax H3 / Hailuo 2.3 完整接入教程：API、ComfyUI 与本地归档
先说明本地部署边界，再完成密钥保护、异步任务、回调、下载归档、ComfyUI 串联与故障排查。
它解决什么问题
先纠正一个容易踩坑的概念
MiniMax 官方文档当前把新一代多模态视频任务称为 **MiniMax-H3**，文本生视频接口仍列出 MiniMax-Hailuo-2.3 等可用模型。官方没有发布可下载的 H3/Hailuo 2.3 权重、推理代码或本地许可证，因此它不是可以离线放进显卡运行的开源模型。本教程中的“本地”只指：你在自己的电脑或服务器运行 ComfyUI/脚本，生成任务由 MiniMax 云端完成，结果下载到自己的素材盘。任何声称提供 H3 本地权重的第三方文件都应先核验来源和哈希。
架构与准备清单
完整链路是：前端或 ComfyUI 提交提示词 → 你的服务端读取环境变量中的 API Key → MiniMax 返回 task_id → 服务端轮询或接收回调 → 获取下载地址 → 立即下载 MP4 和 JSON 元数据 → 写入素材库。不要把 API Key 写进浏览器、工作流 JSON、公开仓库或截图。
准备 Python 3.11+、可访问 api.minimax.io 的网络、MiniMax 平台 API Key、至少 10GB 临时磁盘和 FFmpeg。创建独立目录，分别保存 scripts/、jobs/、media/ 与 logs/。生产环境还应准备 HTTPS 回调地址、任务数据库、重试队列和磁盘配额。
提示词与参数设计
官方文本接口的提示词上限为 2000 字符。镜头命令可以用方括号表达，例如 [Push in]、[Pan left]、[Tracking shot]、[Static shot]；并行运镜建议不超过三个。先写主体和动作，再写环境、光线、镜头、风格，最后写禁止项。需要严格复现时关闭自动优化；需要快速出结果时可以保留优化器。
6 秒任务可选择 768P 或 1080P，10 秒任务使用 768P。先用 6 秒、768P 验证人物、动作和镜头，再提高分辨率，能显著减少无效成本。为每次任务保存模型名、完整提示词、分辨率、时长、任务 ID、提交时间、状态、结果 URL、下载文件哈希与失败信息。
ComfyUI 串联方式
ComfyUI 只是编排层，不会把云模型变成本地模型。最稳妥的做法是用 HTTP/API 节点调用你自己的后端，而不是让节点直接持有 MiniMax Key。工作流可按“文本输入 → 参数校验 → 调用后端 → 轮询状态 → 下载视频 → 预览/保存”组织。若使用第三方节点，只安装可信仓库，固定提交版本，并检查它是否把密钥发送到非 MiniMax 域名。
回调与本地缓存
回调地址首次验证时必须在 3 秒内原样返回 challenge。后续状态可能是 processing、success 或 failed。回调处理要具备幂等性：同一个任务成功通知多次时只下载一次。下载完成后计算 SHA-256，保存原始响应 JSON，并将临时 URL 与本地永久路径分开记录。定时任务应清理失败任务的残留文件，但不得误删已发布素材。
安全与验收
Key 只放在服务端环境变量或密钥管理器；日志对 Authorization 头脱敏；限制单用户并发数；验证回调来源和任务 ID；下载前检查内容类型、文件大小和超时。验收时至少完成一次成功任务、一次错误 Key、一次超时重试、一次重复回调、一次磁盘空间不足模拟，并确认网页刷新后仍能从本地路径播放视频。
常见问题
401/403：Key 无效、账户权限不足或请求头格式错误。- 一直
processing：降低轮询频率并设置总超时，不要重复创建任务。 - 有 URL 但下载失败：结果链接可能短期有效，应在成功后立即缓存。
- ComfyUI 找不到节点：检查自定义节点启动日志及其独立依赖。
- 视频不符合提示：缩短动作链，固定一个镜头命令，关闭或开启提示词优化器做 A/B 对照。
> 技术参数以 MiniMax 官方 API 文档为准；本教程不提供、也不暗示存在 H3 离线权重。
安装 / 开始使用
python -m venv .venv
# Linux/macOS
source .venv/bin/activate
# Windows PowerShell
.venv\Scripts\Activate.ps1
pip install requests python-dotenv在 .env 中写入 MINIMAX_API_KEY=...，不要提交此文件。最小提交脚本：
import os, requests
payload = {
"model": "MiniMax-Hailuo-2.3",
"prompt": "A product rises from mist [Push in], soft rim light.",
"duration": 6,
"resolution": "768P"
}
r = requests.post(
"https://api.minimax.io/v1/video_generation",
headers={"Authorization": f"Bearer {os.environ['MINIMAX_API_KEY']}", "Content-Type": "application/json"},
json=payload,
timeout=60,
)
r.raise_for_status()
print(r.json())拿到 task_id 后使用官方查询任务接口轮询，成功后下载文件到 media/YYYY/MM/。生产环境用数据库保存状态，采用 5、10、20、30 秒退避，设置 30 分钟总超时。