MiniMax-H3 视频接口文档

本文档说明 token-gateway 中 MiniMax-H3 视频任务接口的调用方式、字段约束、响应格式、错误格式与计费口径。文档依据当前项目实现整理，并参考 MiniMax 官方 V2 视频接口形态：

1. 接口概览

方法	路径	用途
`POST`	`/v1/video/minimax/tasks`	提交 MiniMax-H3 视频生成任务
`GET`	`/v1/video/minimax/tasks/{task_id}`	查询任务状态和结果
`DELETE`	`/v1/video/minimax/tasks/{task_id}`	取消或删除任务

2. 通用约定

2.1 Base URL

https://router.253.com

2.2 鉴权

所有接口都需要网关 Token 鉴权。

Authorization: Bearer {API_KEY}
Content-Type: application/json

3. 创建视频任务

3.1 请求

POST https://router.253.com/v1/video/minimax/tasks

字段	类型	必填	说明
`model`	string	是	模型名，`MiniMax-H3`；不能为空。
`resolution`	string	是	分辨率，仅支持 `768P` 或 `2K`。
`duration`	integer	否	视频时长，单位秒；默认 `4`，允许范围 `4` 到 `15`。必须是整数；
`content`	array	是	内容数组，必须非空，且至少包含一个 `text` 非空的文本项作为 prompt。
其他字段	any	否	按 MiniMax 官方 V2 创建接口格式透传给上游；建议只传官方支持字段。

3.3 请求示例：文生视频

curl -X POST 'https://router.253.com/v1/video/minimax/tasks' \
  -H 'Authorization: Bearer {API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "MiniMax-H3",
    "resolution": "768P",
    "duration": 5,
    "content": [
      {"type": "text", "text": "一只橘猫在清晨阳台上伸懒腰，电影感镜头，柔和自然光"}
    ]
  }'

3.4 请求示例：图生视频

{
  "model": "MiniMax-H3",
  "resolution": "2K",
  "duration": 6,
  "content": [
    {
      "type": "text",
      "text": "让画面中的人物缓慢回头并微笑，镜头轻微推进"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/reference.png"
      }
    }
  ]
}

3.5 成功响应

网关返回公开任务 ID。后续查询和删除都必须使用该公开任务 ID，而不是上游原始任务 ID。

{
  "task_id": "task_*****************"
}

4. 查询任务

4.1 请求

GET https://router.253.com/v1/video/minimax/tasks/{task_id}

curl 'https://router.253.com/v1/video/minimax/tasks/task_public_123' \
  -H 'Authorization: Bearer {API_KEY}'

4.2 成功响应

如果任务绑定的是 MiniMax 官方渠道，网关会尽量保留上游官方响应结构，并把响应中的 task_id 或 task.id 改写为公开任务 ID。常见结构如下：

{
  "task": {
    "id": "task_*****************",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1730000000,
    "updated_at": 1730000300,
    "content": {
      "url": "https://cdn.example.com/final.mp4"
    },
    "resolution": "768P",
    "duration": 5,
    "usage": {
      "total_seconds": 5,
      "input_seconds": 0,
      "output_seconds": 5,
      "input_image_count": 1,
      "input_audio_seconds": 0
    }
  }
}

4.3 状态枚举

状态	说明
`queued`	任务已提交或排队中。
`processing`	任务处理中。
`succeeded`	任务成功，通常包含 `content.url`。
`failed`	任务失败，可能包含 `error.message`。
`cancelled`	任务已取消。

5. 取消或删除任务

5.1 请求

DELETE https://router.253.com/v1/video/minimax/tasks/{task_id}

curl -X DELETE 'https://router.253.com/v1/video/minimax/tasks/task_public_123' \
  -H 'Authorization: Bearer {API_KEY}'

5.2 状态规则

当前状态	处理方式
`not_start` / `submitted` / `queued`	成功后本地状态更新为 `cancelled`，并退还预扣额度。
`succeeded` / `failed`	删除记录
`in_progress`	拒绝删除，返回 `invalid_task_status`。
`cancelled`	拒绝删除，返回 `invalid_task_status`。

5.3 成功响应

成功响应沿用 MiniMax 官方任务响应形态，并把任务 ID 改写为公开任务 ID。若使用兼容渠道，网关会兜底返回如下结构：

{
  "task": {
    "id": "task_*****************",
    "status": "cancelled"
  }
}

6. 错误响应

MiniMax-H3 路由会统一返回 MiniMax 风格错误对象；如果上游已经返回官方错误对象，网关会保留该结构。

{
  "type": "error",
  "error": {
    "type": "bad_request_error",
    "message": "invalid params, resolution must be 768P or 2K",
    "http_code": "400"
  },
  "request_id": "test-request-id"
}

场景	说明
JSON 无效	返回 `400 bad_request_error`，message 为 `invalid json body`。
`model` 缺失或为空	返回 `400 bad_request_error`。
`resolution` 非 `768P` / `2K`	返回 `400 bad_request_error`。
`duration` 非整数或超出 `4-15`	返回 `400 bad_request_error`。
`content` 为空或缺少非空文本项	返回 `400 bad_request_error`。
任务不存在或不属于 MiniMax	查询/删除返回 `400 task_not_exist`。
服务端或上游异常	HTTP 状态码大于等于 `500` 时错误类型为 `server_error`。

产品中心

热门搜索

中国站

国际站

视频生成-MiniMax-H3