MiniMax H3 视频生成

MiniMax H3 使用 RootFlowAI 的异步视频接口：先提交任务取得 ID，再查询状态，完成后播放或下载视频。客户端统一使用 https://api.rootflowai.com 和自己的 RootFlowAI API Key。

本页单独说明 H3 的规格和等待方式。Veo 的调用方式仍见 视频生成指引。

模型与规格

模型 ID 统一使用全小写；分辨率仍按上表填写为768P或2K。minimax-h3-2k 是平台用于选择 2K 规格的模型名称。

seconds 必须写成 JSON 字符串，例如 "4"、"8" 或 "15"。不要使用 Veo 的固定 8 秒、720p 参数；H3 按本次请求的整数秒数生成。视频文件的实际播放时长可能与请求秒数略有差异。

分辨率可以省略，平台会使用对应模型的默认值。若显式指定，则必须匹配模型：minimax-h3 对应 768P，minimax-h3-2k 对应 2K，不能靠修改 resolution 跨模型切换规格。

请在 模型价格 确认当前分组、时长与分辨率对应的价格，以 消费日志 的记录为准。任务失败或提交结果不明时，请先核查任务与消费日志，必要时联系服务支持。

计费标准

按请求的输出秒数计费，以下单位为平台额度/秒：

例如SVIP生成4秒视频，768P为1.20额度、2K为1.92额度。最终可用状态及扣费以正式平台模型价格页为准。

在同一 H3 分组中切换清晰度

创建 RootFlowAI API Key 时选择 「MiniMax 视频」 分组，并确认令牌允许 minimax-h3 和 minimax-h3-2k 两个模型。分组用于选择可用服务，model 用于选择视频规格；切换清晰度无需更换 Key 或分组，在创建请求中选择对应模型即可。

从 768P 切换到 2K 时，将 model 改为 minimax-h3-2k，同时将 resolution 改为 2K（或删除该字段，使用默认值）；切回时反向修改。不能只把 minimax-h3 的 resolution 改为 2K；model: "minimax-h3"始终对应768P，2K必须使用minimax-h3-2k。

平台按所选规格安排可用服务，用户无需指定上游渠道。2K 不会自动降为 768P；所选规格暂不可用时会返回错误或任务失败，不能把它当作低清晰度成功结果。不同规格独立计价，会员优惠按当前分组规则计算，具体以模型价格页为准。

清晰度是在创建任务时确定的，已创建任务不能修改；需要另一规格时会创建新的任务并单独计费。若原任务正在生成或提交结果不明，应先核查原任务，不要以“切换清晰度”作为重试方式。

接口流程

POST /v1/videos
  → 取得任务 ID，保存后再进行其他操作

GET /v1/videos/{task_id}
  → queued / in_progress / completed / failed

GET /v1/videos/{task_id}/content
  → completed 后播放或下载 MP4

以上三个接口均使用 RootFlowAI API Key。不要将 API Key 放入 URL 查询参数，也不要把包含 Key 的请求代码直接放在公开网页中。

提交视频任务

请求参数

本页示例使用JSON文生视频或单参考图视频。不传 size，也不需要 stream 或聊天消息格式的 messages。目前不开放多参考图、首尾帧、参考视频或参考音频。

768P 示例

先把自己的 RootFlowAI API Key 设置到环境变量 ROOTFLOWAI_API_KEY。以下请求创建一个 4 秒横屏视频：

curl --connect-timeout 15 --max-time 900 \
  https://api.rootflowai.com/v1/videos \
  -H "Authorization: Bearer ${ROOTFLOWAI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3",
    "prompt": "阳光下木桌上的蓝色陶瓷杯，镜头缓慢推近，柔和自然光，无人物、无文字。",
    "seconds": "4",
    "resolution": "768P",
    "aspect_ratio": "16:9"
  }'

2K 竖屏示例

{
  "model": "minimax-h3-2k",
  "prompt": "一只橘猫安静地坐在窗边，阳光照亮毛发，镜头缓慢推近，保持主体清晰。",
  "seconds": "6",
  "resolution": "2K",
  "aspect_ratio": "9:16"
}

单参考图示例

768P和2K均支持最多一张参考图。使用 image_urls 数组传入一个图片地址；HTTPS地址必须能够公开读取，不能填写本机文件路径或需要登录的网页地址。

{
  "model": "minimax-h3-2k",
  "prompt": "保持参考图中的白色陶瓷杯和蓝色背景，镜头缓慢推近，杯口升起轻微热气。",
  "seconds": "4",
  "resolution": "2K",
  "aspect_ratio": "16:9",
  "image_urls": ["https://your-domain.example/reference.png"]
}

将示例地址替换为自己的可访问图片URL。也可把数组元素替换为完整的 data:image/png;base64,...、data:image/jpeg;base64,... 或 data:image/webp;base64,...；省略号必须替换为图片实际Base64内容，不能直接照抄。图片处理由平台完成，调用方只需使用相同字段。

切换到768P时同时修改 model 为 minimax-h3、resolution 为 768P（或省略resolution）。单参考图沿用相应规格的按秒价格；不要混入首帧/尾帧字段，也不要传入两张或更多图片。提交、查询与下载流程和文生视频相同。

创建响应

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "minimax-h3",
  "status": "queued",
  "progress": 0,
  "created_at": 1792454400
}

保存响应中的 id；如果客户端读取的是兼容字段 task_id，则使用该字段返回的值。后续始终使用平台返回的任务 ID，不要自行拼接或替换。

查询与等待

将创建响应中的任务 ID 设置为 TASK_ID，然后查询：

curl --connect-timeout 15 --max-time 180 \
  "https://api.rootflowai.com/v1/videos/${TASK_ID}" \
  -H "Authorization: Bearer ${ROOTFLOWAI_API_KEY}"

建议每 10–15 秒查询一次，同一任务不要并发轮询。progress 不是线性计时器，长时间保持 0 不代表任务停止。

生成十分钟，会让请求超时吗？

取得任务 ID 后，视频在后台异步生成，不需要让创建连接一直等到视频完成。 客户端定期查询同一个 ID，完成后再下载；本接口采用主动查询，不依赖原连接回传视频或自动推送到客户端。

视频时长与生成耗时不同。例如，10 秒参考图视频可能等待约 8–10 分钟，排队或结果存储准备还可能延长等待。页面显示的“用时”是累计耗时，不是单次 HTTP 请求时长，也不是完成时间承诺。即使累计等待超过 10 分钟或 900 秒，也不应仅因此认定任务失败；以查询返回的任务状态为准。

客户端超时配置建议

如果 SDK 的 timeout 单位是毫秒，900 秒应填写 900000，180 秒填写 180000，1260 秒填写 1260000。不要把“单次请求超时”配置复用为“整个轮询流程的总时限”，也不要让一个 60 秒的计时器在多次查询之间持续倒计时。

自己的服务端、反向代理、网关或云函数也需要允许对应请求等待；客户端设置 900 秒不能覆盖中间层更短的限制。慢创建接入可使用 https://us.rootflowai.com，Key 与 /v1/videos 路径保持一致。受理后始终保留原任务 ID，不因换线路而重新创建。

前端关闭页面或停止轮询不会主动取消已受理的后台任务。请持久化任务 ID，重新打开页面后恢复查询，或使用自己的后台作业定时查询。观察 40–60 分钟仍未完成时，保留 ID 并联系服务支持；客户端应显示“仍在处理中 / 待核查”，不要伪造 failed 状态。

连接中断时怎么处理

• 已取得任务 ID：保留 ID，重新查询原任务。网络超时或临时 502/503/504 时，可等待 10–15 秒后重试 GET；429 遵循响应中的 Retry-After（如有）。401/403 先检查 Key 和权限。上述请求错误均不能直接当作任务 failed，不要重新创建视频。
• 创建时没有收到任务 ID：先到 视频任务 核查最近任务。不要立即重新发送 POST；若无法确认是否受理，联系 服务支持，提供请求时间和模型名。
• 状态仍为 queued 或 in_progress：继续查询，不要因为等待超过一两分钟就自行改成失败。
• 看到 video storage is preparing：说明视频结果仍在准备，稍后查询或下载即可。

播放与下载

任务为 completed 后下载：

curl --connect-timeout 15 --max-time 1260 \
  "https://api.rootflowai.com/v1/videos/${TASK_ID}/content" \
  -H "Authorization: Bearer ${ROOTFLOWAI_API_KEY}" \
  -o minimax-h3.mp4

接口返回视频二进制内容，通常为 video/mp4；它不是一个供客户端再次请求的第三方视频 URL。浏览器或播放器需要携带认证，普通网页建议通过自己的服务端代理视频流，避免将 API Key 暴露给访客。

也可以登录门户的 视频任务 页面查看、预览和下载。视频沿用平台的 7 天保留规则，请在生成完成后及时下载保存，不要把任务页面当作永久备份。

常见问题

为什么提示模型不可用？

先检查模型 ID 是否完全一致，以及当前 Key 的「MiniMax 视频」分组和模型权限。

为什么 `seconds` 不能直接写数字 `4`？

平台视频接口使用字符串类型的 seconds。请写 "seconds": "4"，以保证通过平台请求校验。

为什么 2K 请求被拒绝？

检查是否使用 model: "minimax-h3-2k"，以及 resolution 为 2K 或省略；同时确认当前 Key 有该模型权限。minimax-h3 的对应规格是 768P。不要传入 720p 或像素形式的 size。

可以套用 Veo 的参考图参数吗？

不同视频模型的素材角色和限制不同。H3单参考图使用本页的 image_urls 数组，最多一张；不要复制其他模型的首尾帧或参考视频参数。

相关说明：获取 API Key · Veo 视频指引 · 服务定价