MiniMax-H3 视频 API

MiniMax-H3 支持通过文本、图片、视频和音频异步生成视频。先提交生成任务，再使用返回的 task_id 轮询查询接口，直到任务进入终态。

API 概览

项目	值
模型	`MiniMax-H3`
Base URL	`https://api.exchangetoken.ai`
创建任务	`POST /v2/video_generation`
查询任务	`GET /v2/query/video_generation/{task_id}`
鉴权	`Authorization: Bearer YOUR_API_KEY`
请求格式	`application/json`（上游文档标注的默认值；建议显式发送）

不支持回调地址

请勿传入 callback_url。请使用创建接口返回的平台 task_id 轮询 Exchange Token 查询接口。

创建视频生成任务

http

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

请求字段

字段	类型	必填	默认值	说明
`model`	`string`	是	无	必须为 `MiniMax-H3`
`content`	`object[]`	是	无	多模态输入数组；每个请求必须包含一个非空的 `text` 项
`resolution`	`string`	是	无	`768P` 或 `2K`
`duration`	`integer`	是	无	生成视频时长，范围为 `4` 到 `15` 秒
`ratio`	`string`	条件必填	可省略时为 `adaptive`	`adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4` 或 `9:16`；具体行为见下文

Exchange Token 不接受 MiniMax 上游 API 中的 callback_url 字段。

`content` 内容项

content 中每一项都需要设置 type。媒体项通过嵌套对象中的 url 传入内容地址。

`type`	值字段	支持的 `role`	默认行为	说明
`text`	`text`	—	无	提示词，最多 7,000 个字符；必须至少提供一个非空文本项
`image_url`	`image_url.url`	`first_frame`、`last_frame`、`reference_image`	仅有一张图片且省略 `role` 时，默认为 `first_frame`	首帧、尾帧或参考图片
`video_url`	`video_url.url`	`reference_video`	无	参考视频
`audio_url`	`audio_url.url`	`reference_audio`	无	参考音频

媒体内容可以使用公网 URL 或支持的 Base64 Data URL。整个 JSON 请求体不得超过 64 MB；Base64 会增加体积，因此较大的媒体文件建议使用公网 URL。

支持的生成场景

场景	`content` 组合	`ratio` 规则
文生视频	仅一个 `text` 项	必填，且不能为 `adaptive`
首帧图生视频	`text` + 一个 `first_frame` 图片（也可省略 role）	按 `adaptive` 处理
尾帧图生视频	`text` + 一个 `last_frame` 图片	按 `adaptive` 处理
首尾帧图生视频	`text` + `first_frame` + `last_frame` 图片	按 `adaptive` 处理
参考生视频	`text` + 合法的参考图片、视频、音频组合	可选，默认为 `adaptive`

同一个请求中，首尾帧输入不能与 reference_image、reference_video 或 reference_audio 混用。

需要特别注意，adaptive 不是文生视频的有效默认值：文生视频必须显式选择一个具体比例。图生视频的比例由输入图片决定，即使传入其他合法值也会按 adaptive 处理。参考生视频省略 ratio 时使用 adaptive。

媒体限制

媒体	限制
图片	JPG、JPEG、PNG、WEBP、HEIC 或 HEIF；单张不超过 30 MB；宽高 256–5760 px；宽高比 0.4–2.5；首帧最多 1 张、尾帧最多 1 张、参考图片最多 9 张
视频	MP4 或 MOV；H.264/H.265；单个不超过 50 MB；单段 2–15 秒且总计不超过 15 秒；最多 3 段；宽高 256–5760 px；宽高比 0.4–2.5；23.976–60 FPS
音频	WAV 或 MP3；单个不超过 15 MB；单段 2–15 秒且总计不超过 15 秒；最多 3 段

文生视频示例

bash

curl -sS -X POST "https://api.exchangetoken.ai/v2/video_generation" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "电影感跟拍镜头：一名宇航员走过霓虹灯照亮的雨夜街道，积水中倒影闪烁。"
      }
    ],
    "resolution": "2K",
    "duration": 5,
    "ratio": "16:9"
  }'

图生视频示例

bash

curl -sS -X POST "https://api.exchangetoken.ai/v2/video_generation" \
  -H "Authorization: Bearer YOUR_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-frame.png"},
        "role": "first_frame"
      }
    ],
    "resolution": "768P",
    "duration": 5,
    "ratio": "adaptive"
  }'

参考生视频示例

bash

curl -sS -X POST "https://api.exchangetoken.ai/v2/video_generation" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }'

创建响应

json

{
  "task_id": "sg_vid_xxxxxxxxxxxxxxxx"
}

请保存 Exchange Token 返回的任务 ID，后续查询只需要使用这个 ID。

查询任务

将 {task_id} 替换为创建接口返回的值。

查询接口没有可选请求字段或默认值；路径参数 task_id 和 Authorization 请求头均为必填。

http

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

bash

curl -sS "https://api.exchangetoken.ai/v2/query/video_generation/sg_vid_xxxxxxxxxxxxxxxx" \
  -H "Authorization: Bearer YOUR_API_KEY"

任务状态

状态	含义
`queued`	排队等待执行
`running`	正在生成
`succeeded`	生成成功，从 `task.content.url` 获取视频地址
`failed`	生成失败，查看 `task.error`
`cancelled`	任务已取消

查询响应字段

HTTP 响应体的顶层包含一个 task 对象。

字段	类型	返回条件	说明
`task`	`object`	始终返回	视频生成任务详情

`task` 对象

字段	类型	返回条件	说明
`id`	`string`	始终返回	Exchange Token 平台任务 ID，与查询路径中使用的 ID 相同；不会暴露上游任务 ID
`model`	`string`	始终返回	任务使用的模型；本接口为 `MiniMax-H3`
`status`	`string`	始终返回	当前任务状态：`queued`、`running`、`succeeded`、`failed` 或 `cancelled`
`error`	`object`	失败时	失败详情，字段见下方 `task.error` 表格
`created_at`	`integer`	始终返回	任务创建时间，Unix 秒级时间戳
`updated_at`	`integer`	始终返回	任务最后更新时间，Unix 秒级时间戳
`content`	`object`	成功时	生成结果，字段见下方 `task.content` 表格
`resolution`	`string`	始终返回	请求或输出分辨率：`768P` 或 `2K`
`duration`	`integer`	始终返回	请求或输出视频时长，单位为秒
`usage`	`object`	始终返回	用量信息；实际用量尚不可用时，基础计数字段为 `0`，详见下方 `task.usage` 表格
`ratio`	`string`	可用时	实际输出宽高比；使用自适应比例时，以该字段判断最终选择的比例
`task_type`	`string`	始终返回	在本 Exchange Token 接口中固定为 `generation`
`modality`	`string`	始终返回	在本 Exchange Token 接口中固定为 `video`

`task.content` 对象

字段	类型	返回条件	说明
`url`	`string`	`status=succeeded` 时	生成视频的临时下载地址；请尽快下载或转存

`task.error` 对象

字段	类型	返回条件	说明
`code`	`string`	上游报告失败时	MiniMax 失败代码；平台侧失败时可能不返回该字段
`message`	`string`	`status=failed` 时	可读的失败原因

`task.usage` 对象

字段	类型	返回条件	说明
`total_seconds`	`integer`	始终返回	总计费视频秒数，即 `input_seconds + output_seconds`；用量不可用时为 `0`
`input_seconds`	`integer`	始终返回	输入参考视频的总秒数；未使用参考视频或用量不可用时为 `0`
`output_seconds`	`integer`	始终返回	生成视频的输出秒数；用量不可用时为 `0`
`input_image_count`	`integer`	始终返回	输入图片总数，包括首帧、尾帧和参考图片；没有图片时为 `0`
`input_audio_seconds`	`integer`	返回参考音频用量时	输入参考音频各片段时长之和，按秒取整
`total_tokens`	`integer`	MiniMax 返回时	等效总用量 token，即 `prompt_tokens + completion_tokens`
`prompt_tokens`	`integer`	MiniMax 返回时	由参考视频、图片和参考音频折算的等效输入 token；没有多模态输入用量时为 `0`
`completion_tokens`	`integer`	MiniMax 返回时	由生成视频折算的等效输出 token

表格中的“始终返回”是指查询请求获得成功 HTTP 响应时，包括任务仍在排队、运行或已经失败的情况。部分可选用量字段在 MiniMax 返回实际用量前可能省略。

查询成功响应

json

{
  "task": {
    "id": "sg_vid_xxxxxxxxxxxxxxxx",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1785125529,
    "updated_at": 1785125946,
    "content": {
      "url": "https://example.com/generated-video.mp4"
    },
    "resolution": "2K",
    "duration": 5,
    "usage": {
      "total_seconds": 5,
      "input_seconds": 0,
      "output_seconds": 5,
      "input_image_count": 1,
      "input_audio_seconds": 6,
      "total_tokens": 273890,
      "prompt_tokens": 13500,
      "completion_tokens": 260390
    },
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video"
  }
}

生成视频的 URL 有时效性。任务成功后请尽快下载或转存结果。

查询失败响应

json

{
  "task": {
    "id": "sg_vid_xxxxxxxxxxxxxxxx",
    "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"
  }
}

错误格式

网关错误使用 Exchange Token 的统一错误结构：

json

{
  "error": {
    "type": "invalid_request",
    "message": "content must include a non-empty text item"
  }
}

HTTP 状态码	常见含义
`400`	JSON 或参数无效、传入了不支持的 `callback_url`、缺少提示词，或模型/分辨率/时长不合法
`401` / `403`	API Key 缺失、无效、禁用或无权访问
`402`	配额不足
`404`	任务不存在，或任务不属于当前 API Key
`422`	输入未通过内容安全检查
`429`	请求频率超过限制
`500`	内部错误
`502`	上游请求或响应异常
`503`	无可用渠道或异步任务服务不可用

MiniMax-H3 视频 API ​

API 概览 ​

创建视频生成任务 ​

请求字段 ​

content 内容项 ​

支持的生成场景 ​

媒体限制 ​

文生视频示例 ​

图生视频示例 ​

参考生视频示例 ​

创建响应 ​

查询任务 ​

任务状态 ​

查询响应字段 ​

task 对象 ​

task.content 对象 ​

task.error 对象 ​

task.usage 对象 ​

查询成功响应 ​

查询失败响应 ​

错误格式 ​

MiniMax-H3 视频 API

API 概览

创建视频生成任务

请求字段

`content` 内容项

支持的生成场景

媒体限制

文生视频示例

图生视频示例

参考生视频示例

创建响应

查询任务

任务状态

查询响应字段

`task` 对象

`task.content` 对象

`task.error` 对象

`task.usage` 对象

查询成功响应

查询失败响应

错误格式