Topview API Console

MiniMax-H3

文档更新于 2026-08-03

保持 MiniMax Video Generation V2 的请求与响应结构，平台代管上游鉴权与视频转存。

MiniMax-H3

文档信息

适用环境：生产环境
Base URL：https://api.topview.ai
模型：MiniMax-H3
协议版本：MiniMax Video Generation V2
更新时间：2026-08-10

本接口保持 MiniMax Video Generation V2 的请求和响应结构。平台负责上游鉴权、任务映射与积分扣费，客户端无需持有 MiniMax 官方 API Key。

视频地址原样透传 MiniMax 官方下载链接，该链接有时效，请在任务成功后尽快下载或转存，详见第 5.5 节。

1. 接口概览

当前开放以下接口：

text

POST /v2/video_generation
GET  /v2/query/video_generation/{task_id}

本期暂不开放任务列表、取消/删除任务、H3-Context-IR、视频再生成及 MiniMax 文件管理接口。

2. 鉴权与通用约定

使用 Topview 平台签发的 API Key：

http

Authorization: Bearer sk-你的TopviewAPIKey
Content-Type: application/json

通用约定：

请求与响应均采用 JSON。
客户端无需传递 Topview-Uid 或 Topview-Team-Id。
创建接口返回平台任务 ID，查询时必须使用该 ID。
成功任务的 task.content.url 为 MiniMax 官方下载地址，平台不做改写。
建议即使配置了回调，也保留轮询作为兜底。

3. 推荐调用流程

调用创建接口提交生成参数。
保存响应中的 task_id。
通过查询接口轮询任务状态，或等待 callback_url 回调。
当状态为 succeeded 时，从 task.content.url 获取视频。
当状态为 failed 或 cancelled 时，读取 task.error。

4. 创建视频生成任务

4.1 接口

http

POST https://api.topview.ai/v2/video_generation

4.2 请求字段

model

类型：string
必填：是
固定值：MiniMax-H3

content

类型：array
必填：是
说明：多模态输入数组，至少包含一个非空 text 项。

支持的元素类型：

text：文本提示词，单项最多 7000 个字符。
image_url：图片输入。
video_url：参考视频输入。
audio_url：参考音频输入。

支持的 role：

first_frame：首帧图片。
last_frame：尾帧图片。
reference_image：参考图片。
reference_video：参考视频。
reference_audio：参考音频。

输入组合：

文生视频：仅包含 text。
首帧图生视频：text + first_frame。
尾帧图生视频：text + last_frame。
首尾帧图生视频：text + first_frame + last_frame。
多模态参考生视频：text + 参考图片、视频或音频。

限制：

首尾帧输入与多模态参考输入不能混用。
参考音频不能单独使用，至少还需一张参考图片或一个参考视频。

resolution

类型：string
必填：是
支持值：768P、2K

duration

类型：integer
必填：是
支持范围：4～15 秒

ratio

类型：string
必填：视生成场景而定
支持值：adaptive、21:9、16:9、4:3、1:1、3:4、9:16

规则：

文生视频必须指定具体比例，不能使用 adaptive。
首尾帧图生视频由输入图片确定比例，建议传 adaptive。
多模态参考生视频可传 adaptive 或具体比例。

callback_url

类型：string
必填：否
说明：接收任务状态通知的公网 HTTP/HTTPS 地址。

创建任务时，平台会先向该地址发送 challenge 验证。客户端必须在 3 秒内原样返回 challenge，否则创建失败。

aigc_watermark

类型：boolean
必填：否
默认值：false
说明：是否在生成视频中添加 AIGC 标识。

4.3 文生视频示例

bash

curl -X POST 'https://api.topview.ai/v2/video_generation' \
  -H 'Authorization: Bearer sk-你的TopviewAPIKey' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "电影级镜头，一艘飞船穿过深紫色星云，镜头缓慢推进。"
      }
    ],
    "resolution": "2K",
    "duration": 5,
    "ratio": "16:9",
    "aigc_watermark": false
  }'

4.4 首帧图生视频示例

json

{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "镜头缓慢拉近，人物转头看向远方。"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/first-frame.png"
      },
      "role": "first_frame"
    }
  ],
  "resolution": "2K",
  "duration": 5,
  "ratio": "adaptive"
}

4.5 首尾帧图生视频示例

json

{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "画面从白天平滑过渡到夜晚。"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/first-frame.png"
      },
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/last-frame.png"
      },
      "role": "last_frame"
    }
  ],
  "resolution": "2K",
  "duration": 8,
  "ratio": "adaptive"
}

4.6 多模态参考示例

json

{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "参考人物动作和音色生成一段电影感视频。"
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://example.com/reference.mp4"
      },
      "role": "reference_video"
    },
    {
      "type": "audio_url",
      "audio_url": {
        "url": "https://example.com/reference.mp3"
      },
      "role": "reference_audio"
    }
  ],
  "resolution": "2K",
  "duration": 5,
  "ratio": "adaptive"
}

4.7 媒体限制

请求体总大小不能超过 64 MB，大文件建议使用公网 URL。

图片限制：

支持 JPG、JPEG、PNG、WEBP、HEIC、HEIF。
单张不超过 30 MB。
宽高范围为 256～5760 px。
宽高比范围为 0.4～2.5。
首帧最多 1 张，尾帧最多 1 张，参考图最多 9 张。

参考视频限制：

支持 MP4、MOV。
支持 H.264/H.265 视频编码，AAC/MP3 音频编码。
单文件不超过 50 MB。
最多 3 个视频。
单段时长 2～15 秒，总时长不超过 15 秒。
帧率范围为 23.976～60 FPS。

参考音频限制：

支持 WAV、MP3。
单文件不超过 15 MB。
最多 3 个音频。
单段时长 2～15 秒，总时长不超过 15 秒。

4.8 创建成功响应

json

{
  "task_id": "mvt-平台任务ID"
}

task_id 是 Topview 平台任务 ID，后续查询必须使用该 ID。

5. 查询视频生成任务

5.1 接口

http

GET https://api.topview.ai/v2/query/video_generation/{task_id}

5.2 请求示例

bash

curl -X GET \
  'https://api.topview.ai/v2/query/video_generation/mvt-平台任务ID' \
  -H 'Authorization: Bearer sk-你的TopviewAPIKey'

5.3 任务状态

queued：排队中。
running：生成中，或已生成完成但平台扣费尚未结束。
succeeded：生成与扣费均已完成，content.url 可直接下载。
failed：任务失败。
cancelled：任务已取消。

5.4 成功响应

json

{
  "task": {
    "id": "mvt-平台任务ID",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1785125529,
    "updated_at": 1785125946,
    "content": {
      "url": "https://MiniMax官方下载地址/video.mp4"
    },
    "resolution": "2K",
    "duration": 5,
    "usage": {
      "total_seconds": 5,
      "input_seconds": 0,
      "output_seconds": 5,
      "input_image_count": 0
    },
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video"
  }
}

平台仅在以下步骤全部完成后返回 succeeded：

MiniMax 上游生成成功。
平台完成积分扣费。

在扣费完成前，即使上游已生成成功，查询接口也会返回 running 且不含 content。

5.5 视频地址有效期

content.url 是 MiniMax 官方的临时下载地址，请注意两层时效限制：

链接本身有时效，过期后无法再访问。链接过期时，用同一个 task_id 重新调用查询接口即可获得新的可用链接。
上游只保留最近 7 天内的任务。超过 7 天后查询接口会返回任务不存在，届时将无法再获取任何可用链接。

因此请务必在任务成功后尽快把视频下载并保存到你自己的存储，不要把该地址直接持久化到数据库或前端页面长期引用。

5.6 失败响应

json

{
  "task": {
    "id": "mvt-平台任务ID",
    "model": "MiniMax-H3",
    "status": "failed",
    "error": {
      "code": "1026",
      "message": "video description contains sensitive content"
    },
    "resolution": "2K",
    "duration": 5,
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video"
  }
}

6. Callback 回调

6.1 Challenge 验证

创建请求传入 callback_url 后，平台会发送：

http

POST {callback_url}
Content-Type: application/json

json

{
  "challenge": "随机挑战值"
}

客户端必须在 3 秒内返回 HTTP 2xx，并原样返回：

json

{
  "challenge": "随机挑战值"
}

6.2 状态通知

验证成功后，平台会将任务状态推送至 callback_url。推送体与查询接口响应结构一致：

json

{
  "task": {
    "id": "mvt-平台任务ID",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "content": {
      "url": "https://MiniMax官方下载地址/video.mp4"
    },
    "resolution": "2K",
    "duration": 5,
    "usage": {
      "total_seconds": 5,
      "input_seconds": 0,
      "output_seconds": 5,
      "input_image_count": 0
    },
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video"
  }
}

客户端返回任意 HTTP 2xx 即视为接收成功。非 2xx 或网络异常会触发回调重试。

回调中的 content.url 同样是 MiniMax 官方临时地址，时效约束与 5.5 节一致。回调重试可能发生在链接过期之后，收到回调后请以查询接口获取的最新链接为准。

7. 计费规则

默认价格：

2K：0.80 积分/秒。
768P：0.50 积分/秒。
每个任务前 5 张输入图片免费。
超出 5 张后：0.20 积分/张。
1 元人民币对应 1 平台积分。
支持按账号配置 MiniMax-H3 折扣，生效折扣可在 Overview 页的 Model discounts 查看。

计费公式：

text

原价积分 =
    total_seconds × 分辨率每秒单价
  + max(input_image_count - 5, 0) × 0.20

最终扣费积分 =
    原价积分 × 账号折扣率

结果保留 6 位小数，四舍五入。

计费说明：

创建任务时会检查账户可用余额。
failed、cancelled 任务不扣费。
succeeded 后根据 task.usage 后置扣费。
同一任务只扣费一次。
首次扣费会保存价格和折扣快照，后续价格调整不影响该任务。
扣费未完成前不会交付最终视频地址。
成功后余额不足时，查询接口返回 HTTP 402。

计费示例一，5 秒 2K 文生视频：

text

5 × 0.80 = 4.00 积分

计费示例二，10 秒 768P，包含 7 张输入图片：

text

10 × 0.50 + (7 - 5) × 0.20
= 5.40 积分

若账号折扣为 8 折：

text

5.40 × 0.80
= 4.32 积分

8. 并发与限流

MiniMax 并发按 Topview 用户账号控制，与其他视频模型服务相互隔离。

以下情况会拒绝创建并返回 HTTP 429：

账号未配置 MiniMax 并发额度。
账号的 MiniMax 能力已停用。
当前运行任务数达到账号并发上限。

任务进入 succeeded、failed 或 cancelled 后会释放并发槽位。

9. 错误响应

错误响应结构：

json

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "错误详情",
    "http_code": "400"
  },
  "request_id": "请求追踪ID"
}

常见 HTTP 状态：

400：请求参数、模型或 callback challenge 错误。
401：API Key 缺失、无效或已过期。
402：账户余额不足。
404：任务不存在。
422：输入内容涉及敏感内容。
429：账号并发额度不足或上游限流。
500：服务端或上游调用异常。
503：MiniMax 服务当前未开放。

平台本地错误类型可能包括：

authentication_error
invalid_request_error
insufficient_quota_error
rate_limit_error
api_error
service_unavailable_error

上游返回的非 2xx 错误会保留原始 HTTP 状态和响应体。

排查问题时，请向技术支持提供完整的 request_id 和 task_id，不要提供 API Key。

10. 接入注意事项

不要在前端、日志或工单中暴露 API Key。
媒体 URL 必须可被公网访问。
建议轮询间隔不低于 10 秒。
回调处理应具备幂等能力。
收到 succeeded 后请及时保存视频。
遇到 HTTP 429 时应采用指数退避重试。
视频地址为上游临时链接，不要长期持久化；链接过期后重新查询即可换取新链接，但任务超过 7 天后无法找回。
对 HTTP 400、401、402、404 等确定性错误不应自动重试。

11. 官方协议参考

MiniMax V2 创建任务：https://platform.minimaxi.com/docs/api-reference/video-generation-v2-create
MiniMax V2 查询任务：https://platform.minimaxi.com/docs/api-reference/video-generation-v2-query

对接文档

文档信息

1. 接口概览

2. 鉴权与通用约定

3. 推荐调用流程

4. 创建视频生成任务

4.1 接口

4.2 请求字段

model

content

resolution

duration

ratio

callback_url

aigc_watermark

4.3 文生视频示例

4.4 首帧图生视频示例

4.5 首尾帧图生视频示例

4.6 多模态参考示例

4.7 媒体限制

4.8 创建成功响应

5. 查询视频生成任务

5.1 接口

5.2 请求示例

5.3 任务状态

5.4 成功响应

5.5 视频地址有效期

5.6 失败响应

6. Callback 回调

6.1 Challenge 验证

6.2 状态通知

7. 计费规则

8. 并发与限流

9. 错误响应

10. 接入注意事项

11. 官方协议参考