MiniMax H3 调用指南

Base URL: https://router.flatkey.ai 当你需要文生视频、首尾帧控制，或图片、视频和音频参考时，可以使用 MiniMax-H3。所有请求都使用同一套异步流程：创建任务、轮询状态、下载最终 MP4。

多种输入方式

使用文本、首尾帧图片或图片、视频、音频参考生成视频。

统一异步流程

用 POST /v1/videos 创建任务，用 GET /v1/videos/{task_id} 轮询，再从 metadata.url 下载视频。

创建任务和查询状态时都要使用以下鉴权头：

Authorization: Bearer YOUR_FLATKEY_API_KEY

请保护好 API Key，不要把它贴到公开日志、页面或工单中。

创建第一个 H3 视频

1. 提交文生视频任务

使用 MiniMax-H3 模型和文本提示词调用 POST /v1/videos。纯文本请求必须显式指定画面比例，并且不能使用 adaptive。

curl --fail-with-body -sS https://router.flatkey.ai/v1/videos \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "纸船穿过雨后的水洼，电影感微距镜头"
      }
    ],
    "resolution": "768P",
    "duration": 6,
    "ratio": "16:9",
    "aigc_watermark": false
  }'

curl.exe --fail-with-body -sS https://router.flatkey.ai/v1/videos `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" `
  -H "Content-Type: application/json" `
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "纸船穿过雨后的水洼，电影感微距镜头"
      }
    ],
    "resolution": "768P",
    "duration": 6,
    "ratio": "16:9",
    "aigc_watermark": false
  }'

响应会在 id 和 task_id 中返回公开任务 ID：

{
  "id": "task_3f9a00000000000000000000000000e2",
  "task_id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "model": "MiniMax-H3",
  "status": "queued",
  "progress": 0
}

保存返回的 task_...。后续查询任务时需要使用它。

2. 轮询并下载结果

重复调用 GET /v1/videos/{task_id}，直到 status 变成 completed 或 failed。状态变成 completed 后，从 metadata.url 读取临时下载地址。

TASK_ID="task_3f9a00000000000000000000000000e2"

curl --fail-with-body -sS \
  "https://router.flatkey.ai/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY"

# 重复查询，直到 status 变成 completed。
# 然后复制响应中的 metadata.url，粘贴到下面。
VIDEO_URL="PASTE_METADATA_URL_HERE"
curl --fail --location "$VIDEO_URL" --output minimax-h3.mp4

$taskId = "task_3f9a00000000000000000000000000e2"

while ($true) {
  $result = curl.exe --fail-with-body -sS `
    "https://router.flatkey.ai/v1/videos/$taskId" `
    -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" | ConvertFrom-Json
  Write-Host "status: $($result.status)"

  if ($result.status -eq "completed") { break }
  if ($result.status -eq "failed") {
    $result | ConvertTo-Json -Depth 10
    exit 1
  }
  Start-Sleep -Seconds 5
}

curl.exe --fail --location $result.metadata.url --output minimax-h3.mp4

metadata.url 是临时下载地址，不需要 Flatkey 鉴权头。任何拿到该地址的人都能在地址失效前访问生成的视频。请把它视为私密信息，不要记录到日志、公开或分享。请尽快下载视频并保存到自己的存储中。重复查询任务不会刷新已经失效的地址。

选择输入方式

每个请求都必须包含非空文本。你可以再添加首尾帧或参考素材来控制结果。

输入	`type`	必须使用的 `role`	数量限制
提示词	`text`	不要设置 `role`	所有文本合计最多 7,000 个 Unicode 字符
首帧	`image_url`	`first_frame`，也可以省略 `role`	1 张
尾帧	`image_url`	`last_frame`	1 张
参考图片	`image_url`	`reference_image`	9 张
参考视频	`video_url`	`reference_video`	3 段
参考音频	`audio_url`	`reference_audio`	3 段；同时还要提供参考图片或参考视频

不要在同一个请求中混用首尾帧和参考素材。每个 content 元素只能包含一种与 type 对应的载荷。

控制首帧和尾帧

当你希望视频在两张图片之间自然过渡时，使用 first_frame 和 last_frame。

curl --fail-with-body -sS https://router.flatkey.ai/v1/videos \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "镜头缓慢拉远，晨雾穿过山谷"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/first.jpg" },
        "role": "first_frame"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/last.jpg" },
        "role": "last_frame"
      }
    ],
    "resolution": "2K",
    "duration": 8,
    "ratio": "adaptive"
  }'

使用参考素材生成

参考素材可以帮助你保持主体、运动风格或声音一致。参考音频不能作为唯一的媒体输入。

curl --fail-with-body -sS https://router.flatkey.ai/v1/videos \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "保持人物和运动风格一致，让角色穿过雪中的街道"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/character.jpg" },
        "role": "reference_image"
      },
      {
        "type": "video_url",
        "video_url": { "url": "https://example.com/motion.mp4" },
        "role": "reference_video"
      },
      {
        "type": "audio_url",
        "audio_url": { "url": "https://example.com/ambience.mp3" },
        "role": "reference_audio"
      }
    ],
    "resolution": "768P",
    "duration": 10,
    "ratio": "adaptive"
  }'

请求设置

字段	是否必填	支持的值
`model`	是	`MiniMax-H3`
`content`	是	文本，以及可选的首尾帧或参考素材
`resolution`	是	`768P` 或 `2K`，区分大小写
`duration`	是	`4` 到 `15` 秒之间的整数
`ratio`	纯文本请求必填	`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`；有媒体时可用 `adaptive`
`aigc_watermark`	否	`true` 或 `false`

请求包含媒体且省略 ratio 时，Flatkey 会使用 adaptive。纯文本请求必须显式使用非 adaptive 的比例。

理解任务结果

`status`	含义
`queued`	任务已创建，正在等待执行。
`in_progress`	正在生成视频。`progress` 的范围是 0 到 100。
`completed`	视频已生成，可以从 `metadata.url` 下载。
`failed`	生成失败。请读取 `error.code` 和 `error.message`。

对于 H3 视频响应，通用 usage 字段表示秒数：

usage.completion_tokens 表示生成视频的输出时长。
usage.total_tokens 表示总计费时长，其中包含参考视频输入时长。

这些值的单位是秒，不是语言模型 token。最终费用请以 Flatkey 控制台中的用量日志为准。

当前限制

不支持 callback_url。请轮询任务状态。
不支持任务列表、取消、删除、再生成和 remix。
不支持 MiniMax-H3-Context-IR。
处理任务期间，远程素材 URL 必须保持可访问。

错误码	检查方法
`invalid_duration`	把 `duration` 设置为 `4` 到 `15`。
`invalid_resolution`	使用准确的 `768P` 或 `2K`。
`invalid_ratio`	使用支持的比例。纯文本请求不能省略比例或使用 `adaptive`。
`invalid_content`	检查提示词、`role`、素材数量和不能混用的输入组合。
`unsupported_callback_url`	删除 `callback_url`，改为轮询任务。

快速入门

代码接入

主流 AI 工具

媒体生成

热门模型

控制台

参考

MiniMax H3 调用指南

多种输入方式

统一异步流程

创建第一个 H3 视频

1. 提交文生视频任务

2. 轮询并下载结果

选择输入方式

控制首帧和尾帧

使用参考素材生成

请求设置

理解任务结果

当前限制

多种输入方式

统一异步流程

​创建第一个 H3 视频

​1. 提交文生视频任务

​2. 轮询并下载结果

​选择输入方式

​控制首帧和尾帧

​使用参考素材生成

​请求设置

​理解任务结果

​当前限制

创建第一个 H3 视频

1. 提交文生视频任务

2. 轮询并下载结果

选择输入方式

控制首帧和尾帧

使用参考素材生成

请求设置

理解任务结果

当前限制