MiniMax H3 视频任务 API

MiniMax H3 视频任务 API 提供异步视频生成能力。创建任务后，可通过任务 ID 查询生成进度、查看任务列表或取消尚未结束的任务。

当前共开放四个接口：

功能	方法	路径
创建视频任务	`POST`	`/minimax/v2/video_generation`
查询单个任务	`GET`	`/minimax/v2/query/video_generation/{task_id}`
查询任务列表	`GET`	`/minimax/v2/query/video_generation`
取消任务	`DELETE`	`/minimax/v2/video_generation/{task_id}`

接入信息

请求地址


https://cp.compshare.cn

身份认证

所有请求都需要在 Authorization 请求头中携带模型 API Key：


Authorization: Bearer <YOUR_API_KEY>

请使用以 sk-ml- 开头的模型 API Key，并妥善保管。不要在浏览器前端、公开仓库或日志中暴露完整 Key。

创建视频任务

创建一个异步视频生成任务。接口会根据 content 中的素材类型，自动判断文生视频、首尾帧生视频或参考素材生视频模式。


POST https://cp.compshare.cn/minimax/v2/video_generation

请求头

名称	必填	描述
Authorization	是	`Bearer <YOUR_API_KEY>`
Content-Type	是	固定为 `application/json`
Accept	否	建议设置为 `application/json`
Idempotency-Key	否	幂等键。相同 Key 会返回先前创建的任务；创建新任务时应使用新的值

请求参数

名称	类型	必填	描述	示例值
model	String	是	模型名称，当前固定为 `MiniMax-H3`	`MiniMax-H3`
content	Array of Object	是	输入内容数组，必须包含至少一个非空文本项；元素结构见下表	`[{"type":"text","text":"一只猫在海边奔跑"}]`
resolution	String	是	视频分辨率，当前仅支持 `768P`	`768P`
duration	Integer	是	视频时长，取值范围 `4`～`15` 秒	`5`
ratio	String	条件必填	宽高比。纯文生视频时必须传入且不能为 `adaptive`	`16:9`
callback_url	String	否	当前暂不支持；传入非空值会返回参数错误	—
aigc_watermark	Boolean	否	当前仅支持 `false`；传入 `true` 会返回参数错误	`false`

ratio 支持：adaptive、21:9、16:9、4:3、1:1、3:4、9:16。

content 元素结构

名称	类型	必填	描述	示例值
type	String	是	内容类型：`text`、`image_url`、`video_url` 或 `audio_url`	`text`
text	String	条件必填	`type=text` 时必填。所有文本合并后最多 5000 个字符	`一只猫在海边奔跑`
image_url.url	String	条件必填	`type=image_url` 时必填，填写可访问的图片 URL	`https://example.com/frame.png`
video_url.url	String	条件必填	`type=video_url` 时必填，填写可访问的视频 URL	`https://example.com/reference.mp4`
audio_url.url	String	条件必填	`type=audio_url` 时必填，填写可访问的音频 URL	`https://example.com/reference.mp3`
role	String	条件必填	素材用途，取值规则见下表	`first_frame`

素材类型与 role

type	role	用途
`text`	不传	视频提示词
`image_url`	`first_frame`	视频首帧；省略 `role` 时也按首帧处理
`image_url`	`last_frame`	视频尾帧，必须同时提供首帧
`image_url`	`reference_image`	参考图片
`video_url`	`reference_video`	参考视频
`audio_url`	`reference_audio`	参考音频

使用素材时请注意：

每个请求都必须包含至少一个非空的 text 内容项。
最多支持 1 张首帧和 1 张尾帧；尾帧不能脱离首帧单独使用。
最多支持 9 张参考图片、3 个参考视频和 3 个参考音频。
首尾帧素材不能与参考图片、参考视频或参考音频混用。
纯文生视频必须明确填写非 adaptive 的 ratio。

文生视频示例


curl -X POST 'https://cp.compshare.cn/minimax/v2/video_generation' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: video-generation-001' \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "一只橘猫戴着墨镜，在海边驾驶红色跑车，阳光明媚，电影质感，镜头缓慢向前推进"
      }
    ],
    "resolution": "768P",
    "duration": 5,
    "ratio": "16:9",
    "aigc_watermark": false
  }'

首帧生视频示例


curl -X POST 'https://cp.compshare.cn/minimax/v2/video_generation' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: image-to-video-001' \
  -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"
  }'

响应参数

名称	类型	描述	示例值
task_id	String	视频任务 ID，后续查询和取消任务时使用	`019xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`


{
  "task_id": "019xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

查询单个任务

根据任务 ID 查询任务状态和结果。任务成功后，content.url 会返回可下载的视频地址。


GET https://cp.compshare.cn/minimax/v2/query/video_generation/{task_id}

路径参数

名称	类型	必填	描述	示例值
task_id	String	是	创建接口返回的任务 ID	`019xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`

请求示例


curl 'https://cp.compshare.cn/minimax/v2/query/video_generation/<TASK_ID>' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Accept: application/json'

响应参数

响应顶层包含 task 对象。

名称	类型	描述
task.id	String	任务 ID
task.model	String	模型名称，当前为 `MiniMax-H3`
task.status	String	任务状态，详见「任务状态」
task.error	Object	失败信息；失败时包含 `code` 和 `message`
task.created_at	Integer	任务创建时间，Unix 时间戳
task.updated_at	Integer	任务更新时间，Unix 时间戳
task.content.prompt	String	创建任务时提交的提示词
task.content.url	String	视频下载地址，仅成功任务返回
task.resolution	String	视频分辨率
task.duration	Integer	视频时长，单位为秒
task.ratio	String	视频宽高比
task.task_type	String	固定为 `generation`
task.modality	String	固定为 `video`
task.usage	Object	成功任务的用量信息

响应示例


{
  "task": {
    "id": "019xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1786686200,
    "updated_at": 1786686260,
    "content": {
      "prompt": "一只橘猫在海边驾驶跑车",
      "url": "https://example.com/generated-video.mp4"
    },
    "resolution": "768P",
    "duration": 5,
    "usage": {
      "total_seconds": 5,
      "output_seconds": 5
    },
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video"
  }
}

查询任务列表

分页查询当前公司下的 MiniMax H3 视频任务。相同公司下的多个模型 API Key 共享任务列表。


GET https://cp.compshare.cn/minimax/v2/query/video_generation

查询参数

名称	类型	必填	描述	示例值
page_num	Integer	否	页码，从 `1` 开始，默认 `1`	`1`
page_size	Integer	否	每页数量，默认 `20`，最大 `100`	`20`
filter.status	String	否	状态筛选：`queued`、`running`、`succeeded`、`failed`、`cancelled`	`succeeded`
filter.model	String	否	模型筛选，当前仅支持 `MiniMax-H3`	`MiniMax-H3`
filter.task_type	String	否	任务类型，当前仅支持 `generation`	`generation`

当前不支持 filter.task_ids，传入该参数会返回参数错误。

请求示例


curl -G 'https://cp.compshare.cn/minimax/v2/query/video_generation' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Accept: application/json' \
  --data-urlencode 'page_num=1' \
  --data-urlencode 'page_size=20' \
  --data-urlencode 'filter.status=succeeded'

响应参数

名称	类型	描述
items	Array of Object	任务列表，元素结构与单个任务查询中的 `task` 相同
total	Integer	符合筛选条件的任务总数

列表接口不会额外获取视频下载地址。如需获取成功任务的 content.url，请使用任务 ID 调用单个任务查询接口。


{
  "items": [
    {
      "id": "019xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "model": "MiniMax-H3",
      "status": "succeeded",
      "content": {
        "prompt": "一只橘猫在海边驾驶跑车"
      },
      "resolution": "768P",
      "duration": 5,
      "ratio": "16:9",
      "task_type": "generation",
      "modality": "video"
    }
  ],
  "total": 1
}

取消任务

取消尚未结束的视频任务。该操作仅取消任务执行，不会物理删除任务历史记录。


DELETE https://cp.compshare.cn/minimax/v2/video_generation/{task_id}

路径参数

名称	类型	必填	描述	示例值
task_id	String	是	要取消的任务 ID	`019xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`

请求示例


curl -X DELETE \
  'https://cp.compshare.cn/minimax/v2/video_generation/<TASK_ID>' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Accept: application/json'

响应参数

名称	类型	描述	示例值
task_id	String	被取消的任务 ID	`019xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
action	String	固定为 `delete`	`delete`
status	String	当前任务状态	`cancelled`


{
  "task_id": "019xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "action": "delete",
  "status": "cancelled"
}

任务已被执行节点领取时，取消接口第一次返回的 status 可能仍是 running。这表示取消请求已经提交；请稍后调用单个任务查询接口，直到状态变为 cancelled。

任务状态

状态	描述
`queued`	任务正在排队
`running`	任务正在生成或上传结果
`succeeded`	任务生成成功，可通过单个任务查询获取视频地址
`failed`	任务生成失败，查看 `error` 获取失败原因
`cancelled`	任务已取消

典型状态流转：


queued → running → succeeded
queued → cancelled
running → cancelled
queued / running → failed

错误响应

请求格式或参数校验失败时，返回如下结构：


{
  "type": "error",
  "error": {
    "type": "bad_request_error",
    "message": "duration must be between 4 and 15",
    "http_code": "400"
  },
  "request_id": "request-xxxx"
}

下游服务的业务错误可能保持 CompShare API 原始格式返回：


{
  "RetCode": 8039,
  "Message": "job not found",
  "request_uuid": "request-xxxx"
}