MiniMax H3 API 指南：文生视频与参考素材接入

如果客户端把 MiniMax H3 的所有型号都当成同一套规格，生成请求很容易失败。模型 ID 会影响时长和分辨率校验；输入模式则决定首尾帧、参考图片、视频和音频能否同时提交。

本文依据截至 2026 年 10 月 22 日 ToAPIs 前端中的请求契约整理，是接入指南，不是上游性能测试或当前账号报价。正式调用前，请先确认账号已开通对应型号。

快速开始

ToAPIs API 示例使用 POST /v1/videos/generations 提交视频生成任务。请求需要 Bearer API Key、已启用的模型 ID、提示词、时长和画幅比例：

curl -X POST "https://api.toapis.com/v1/videos/generations" \
  -H "Authorization: Bearer $TOAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3",
    "prompt": "A slow cinematic pan across a quiet coastal town at sunrise",
    "duration": 5,
    "ratio": "16:9"
  }'

生成是异步任务。请读取账号 API 响应中返回的任务标识，并使用账号文档指定的状态接口查询。除非文档明确给出响应结构，不要假设任务 ID 一定在某个固定 JSON 路径下。

import os
import requests

BASE_URL = "https://api.toapis.com/v1"
headers = {"Authorization": f"Bearer {os.environ['TOAPIS_API_KEY']}"}

response = requests.post(
    f"{BASE_URL}/videos/generations",
    headers=headers,
    json={
        "model": "minimax-h3",
        "prompt": "A slow cinematic pan across a quiet coastal town at sunrise",
        "duration": 5,
        "ratio": "16:9",
    },
    timeout=30,
)
response.raise_for_status()
print("Submission response:", response.json())

示例先打印响应，而不猜测任务 ID 或视频链接字段。将解析逻辑与账号文档中的响应格式对齐，避免接口外层结构变化时把未完成的任务误判为成功。

使用准确的模型 ID

前端将 minimax-h3 和 minimax-h3-global 识别为基础型号，并识别包含 minimax-h3-max 的型号。例如 Turbo 型号 ID 为 minimax-h3-max-turbo。请使用模型目录显示的完整 ID，不要自行缩写或猜测别名。

当前前端校验的规格如下：

以上是前端校验约束，不代表所有账号或上游路由都开放相同能力。当前客户端仅为精确 ID minimax-h3-max 添加 1080P，不要推断 Turbo、-global 别名或全部 H3 型号均支持 1080P。

两种素材模式二选一

H3 表单支持两类互斥工作流：

1. 首尾帧模式：最多提供一个 first_frame_image 和一个 last_frame_image。有帧素材时，客户端会使用自适应画幅。
2. 参考素材模式：提交参考图片、视频和/或音频，不要同时提交首尾帧。该模式使用所选画幅比例。

首帧请求示例：

{
  "model": "minimax-h3",
  "prompt": "The subject turns toward the camera as the camera gently moves forward",
  "duration": 5,
  "ratio": "16:9",
  "first_frame_image": ["https://example.com/starting-frame.jpg"]
}

参考素材请求示例：

{
  "model": "minimax-h3",
  "prompt": "Use the supplied references to guide the scene and motion",
  "duration": 5,
  "ratio": "16:9",
  "media_mode": "reference",
  "reference_images": ["https://example.com/character-reference.jpg"],
  "reference_videos": ["https://example.com/motion-reference.mp4"]
}

上传素材的具体值格式取决于网关的素材上传流程。这里展示的是请求字段，不代表每条路由都接受任意公开 URL。请使用上传流程返回的 URL 或素材 ID。

当前前端限制包括：最多 9 张参考图、3 段参考视频和 3 段参考音频；参考素材总数不超过 12。每段参考视频时长需为 2–15 秒，视频总时长不超过 15 秒。音频参考必须同时包含至少一项视觉素材。Turbo 不接受参考素材。

提交前应先完成模式、数量和时长校验。输入模式混用、数量超限或缺少视觉参考时，前端会拒绝请求。

提示词、画幅与可选参数

提示词必填，当前前端限制为 7,000 个 Unicode 字符。建议用普通语言描述主体、场景、动作和视觉目标。除非上游文档明确定义特殊语法，否则应把 [Pan Left] 之类的字符串视作普通提示词文本；前端契约无法证明它们是 H3 原生指令。

请求构造器会按型号路由处理 prompt_optimizer、watermark 和 seed 等可选项。不要假设这些字段在所有上游渠道中都相同。切换型号时，也要清除旧型号遗留且当前型号不支持的字段。

前端接受 adaptive、21:9、16:9、4:3、1:1、3:4 和 9:16。首尾帧输入会强制采用 adaptive；文生视频选择 adaptive 时会归一化为 16:9，参考素材模式则保留所选的受支持画幅。

分辨率与画幅是两个不同参数：画幅决定画面形状，分辨率由型号路由决定。选项名称大小写也会因型号不同而异（例如 768p 与 768P），不要在全局逻辑中擅自统一大小写。

轮询、错误与重试

提交任务后，保存任务标识并查询账号文档指定的状态端点。轮询应采用有上限的退避策略，设置总时限，并区分任务失败与客户端等待超时。等待超时不代表上游任务已经失败；重试计费请求前，应先查询原任务，避免重复生成。

客户端至少应检查 HTTP 状态、按文档解析响应、在已记录的终态停止轮询，并限制重试次数和总耗时。日志可以保存请求或任务标识，但不要记录 API Key 或私有素材 URL。

这些是通用诊断类别，不保证与 ToAPIs 每条路由的错误码完全一致。

定价、隐私与上线检查

价格、可用性、退款和 SLA 可能因型号、路由和账号而异。本文不引用每秒价格或可用性承诺。请以当前模型目录和账号报价为准，不要把规划稿中的价格当成生产报价。

参考素材属于用户数据。上传前校验文件类型、大小和数量，只处理用户有权使用的素材，并按产品的数据保留规则管理图片、视频和音频。不要为了演示方便把私人素材放到公开 URL，也不要把临时素材链接写入长期日志。

上线前，至少对账号已启用的每个型号分别测试有效请求，并为小数时长、不支持的分辨率、超量素材、混合模式和 Turbo 参考素材编写负向测试。切换型号后，确认界面会清除不兼容值。使用本地夹具或经批准的测试账号验证响应字段和任务状态；本文未调用线上接口验证服务行为。

相关入口

• 浏览视频模型
• 在 Playground 打开 MiniMax H3
• 在 Playground 打开 MiniMax H3 Max Turbo