MiniMax H3 视频任务 API

MiniMax H3 视频任务 API 提供异步视频生成、任务管理、积分查询和 Skill 管理能力。创建任务后，可通过任务 ID 查询生成进度，也可以通过回调接收状态变化。

当前共开放十个接口：

功能	方法	路径
创建视频任务	`POST`	`/minimax/v2/video_generation`
查询单个任务	`GET`	`/minimax/v2/query/video_generation/{task_id}`
查询任务列表	`GET`	`/minimax/v2/query/video_generation`
查询积分套餐包	`GET`	`/minimax/v2/query/point_packages`
查询积分余额	`GET`	`/minimax/v2/query/point_usage_summary`
取消任务	`DELETE`	`/minimax/v2/video_generation/{task_id}`
查询 Skill 列表	`GET`	`/minimax/v2/skills`
创建 Skill	`POST`	`/minimax/v2/skills`
更新 Skill	`PUT`	`/minimax/v2/skills/{skill_id}`
删除 Skill	`DELETE`	`/minimax/v2/skills/{skill_id}`

接入信息

请求地址


https://cp.compshare.cn

身份认证

获取 API Key

进入优云智算视频工作台。
点击页面左侧工具栏中的 API 按钮，打开“API 密钥”窗口。
如需创建新密钥，可填写密钥名称（选填，默认为 default），然后点击 创建密钥。每个账号最多可创建 3 个视频生成 API Key。
点击密钥右侧的复制图标，复制以 sk-ml- 开头的 API Key。

API Key 用于调用视频生成 API，请仅在服务端保存和使用。不要通过聊天、截图、前端代码、公开仓库或日志泄露完整密钥。

所有请求都需要在 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	否	幂等键，最多 128 个字符。相同 Key 会返回先前创建的任务；创建新任务时应使用新的值

请求参数

名称	类型	必填	描述	示例值
model	String	是	模型名称，支持 `MiniMax-H3` 和兼容别名 `minimax-h3-lite`	`MiniMax-H3`
content	Array of Object	是	输入内容数组，至少包含一个元素；元素结构见下表	`[{"type":"text","text":"一只猫在海边奔跑"}]`
resolution	String	否	输出分辨率档位，支持 `768P`、`1080P`、`2K`，默认 `768P`，区分大小写	`1080P`
duration	Integer	否	视频时长，取值范围 `4`～`30` 秒（含边界，支持范围内的整数），默认 `5`	`5`
ratio	String	否	宽高比，默认 `16:9`；有图片素材时可传 `adaptive`，自动选择最接近素材比例的原生尺寸	`16:9`
callback_url	String	否	任务状态回调地址，必须是可通过公网访问的绝对 `http` 或 `https` URL，最多 1024 个字符	`https://api.example.com/callbacks/minimax-h3`
callback_token	String	否	调用方自定义的回调校验 Token；平台回调时会通过 `X-Callback-Token` 请求头原样传回。最多 512 个字符，使用时必须同时传入 `callback_url`	`<YOUR_CALLBACK_SECRET>`
use_context_ir	Boolean	否	是否启用 Context-IR 提示词优化，默认 `false`；只有显式传入 `true` 才会启用	`true`
skill_id	String	否	使用指定 Skill 优化提示词；传入时必须同时设置 `use_context_ir=true`。Skill ID 可通过 Skill 列表或创建接口获取	`skill-019xxxxx`
mute_audio	Boolean	否	是否移除生成视频的音轨，默认 `false`；传入 `true` 时交付无声视频	`false`
aigc_watermark	Boolean	否	是否添加 AIGC 水印，默认 `false`	`false`

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

use_context_ir 省略时按 false 处理，系统会直接使用原始提示词生成视频。如需启用 Context-IR 提示词优化，创建请求必须显式包含 "use_context_ir": true；启用后，系统会先优化提示词，再进入视频生成阶段。

skill_id 只在 Context-IR 提示词优化阶段生效，因此不能单独使用。需要无声视频时设置 "mute_audio": true；该参数控制最终交付视频是否保留音轨，与提示词优化开关相互独立。

分辨率参数

resolution 建议明确填写下列三个值之一：

请求值	处理方式	当前积分消耗
`768P`	MiniMax H3 原生分辨率，不进行后置超分	10 积分/秒
`1080P`	原生视频生成完成后进行 1080P 超分	15 积分/秒（基础 10 + 超分 5）
`2K`	原生视频生成完成后进行 2K 超分	20 积分/秒（基础 10 + 超分 10）

例如，生成 1080P 或 2K 视频时，请分别传入：


{
  "resolution": "1080P"
}


{
  "resolution": "2K"
}

请求值区分大小写。只有 1080P 和 2K 会启用对应的后置超分；省略该参数，或传入 1K、1080p、2k、720P、4K 等非标准值时，不会启用超分，按原生 768P 处理。积分单价如有调整，以控制台展示为准。

1080P 和 2K 通过后置超分生成，实际输出宽高会根据 ratio 计算。如果超分未成功，系统会降级交付原生 768P 视频并释放超分加价部分；终态任务响应中的 resolution 会返回实际交付的 768P。

content 元素结构

名称	类型	必填	描述	示例值
type	String	是	内容类型：`text`、`image_url`、`video_url` 或 `audio_url`	`text`
text	String	条件必填	`type=text` 时填写。纯文生视频必须包含非空文本；所有文本合并后最多 7000 个字符	`一只猫在海边奔跑`
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` 处理	`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 个参考音频。
所有参考图片、参考视频和参考音频合计最多 12 个；参考音频不能单独使用，必须同时提供至少一张参考图片或一个参考视频。
首尾帧素材不能与参考图片、参考视频或参考音频混用。
ratio=adaptive 主要用于图片素材模式；纯文生视频省略 ratio 或传入 adaptive 时按默认 16:9 处理。

素材地址与文件大小

素材可使用平台能够直接访问的公网 http/https URL，也支持 Data URL。公网 URL 不能指向回环、内网或其他非公网地址；如地址需要登录、临时 Cookie 或额外请求头，平台将无法下载。

素材类型	单个文件上限	平台预处理
图片	30 MiB	短边超过 1080 像素时会等比缩小
视频	50 MiB	会规范为 MP4/H.264、24 FPS，短边最大 720 像素
音频	15 MiB	保留原始音频并转存

使用 Data URL 会增大 JSON 请求体，请求体总大小上限为 72 MiB。一次提交多个较大素材时，建议使用公网 URL。

文生视频示例


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",
    "use_context_ir": true,
    "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",
    "use_context_ir": true
  }'

使用 Skill 生成无声视频

先通过「查询 Skill 列表」或「创建 Skill」取得 skill_id，再将它与 use_context_ir=true 一起提交：


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: skill-video-generation-001' \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "一辆跑车驶过雨夜街道，霓虹灯倒映在路面"
      }
    ],
    "resolution": "1080P",
    "duration": 5,
    "ratio": "16:9",
    "use_context_ir": true,
    "skill_id": "skill-019xxxxx",
    "mute_audio": true
  }'

状态回调

创建任务时传入 callback_url 后，任务公开状态发生变化时，平台会向该地址发送 POST 请求。创建成功后会先推送一次当前排队状态；任务成功时，回调结果中的 task.content.url 会包含视频下载地址。

建议始终同时设置 callback_token。这是由调用方自行生成和保存的回调密钥，平台不会替你生成，也不会进行 challenge 握手。平台回调时会把这个值原样放入 X-Callback-Token 请求头，接收端必须校验该请求头后再处理回调内容。

callback_token 不是模型 API Key。不要把 sk-ml- API Key 填入 callback_token，也不要在响应体、日志或前端代码中暴露回调 Token。

带回调的创建示例


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: callback-video-generation-001' \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "一艘帆船驶过金色海面，电影感，镜头缓慢拉远"
      }
    ],
    "resolution": "768P",
    "duration": 5,
    "ratio": "16:9",
    "callback_url": "https://api.example.com/callbacks/minimax-h3",
    "callback_token": "<YOUR_CALLBACK_SECRET>"
  }'

如果传入 callback_token 但没有传入 callback_url，创建接口会返回参数错误。

平台发出的回调请求


POST /callbacks/minimax-h3 HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-Callback-Token: <YOUR_CALLBACK_SECRET>

只有创建任务时提供了非空的 callback_token，回调请求才会携带 X-Callback-Token。该请求头的值与创建任务时提交的 callback_token 完全一致。

回调 JSON 与「查询单个任务」接口使用相同的 {"task": {...}} 结构，因此可以复用同一套数据模型解析。成功回调示例：


{
  "task": {
    "id": "019xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1786686200,
    "updated_at": 1786686260,
    "content": {
      "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",
    "estimated_remaining_seconds": 0
  }
}

接收端 Token 校验示例

下面以 FastAPI 为例。请把回调 Token 保存在服务端环境变量中，并使用恒定时间比较，避免直接记录或返回 Token：


import os
import secrets
 
from fastapi import FastAPI, Header, HTTPException, Request
 
app = FastAPI()
expected_token = os.environ["MINIMAX_CALLBACK_TOKEN"].encode()
 
 
@app.post("/callbacks/minimax-h3")
async def receive_minimax_callback(
    request: Request,
    callback_token: str | None = Header(default=None, alias="X-Callback-Token"),
):
    received_token = (callback_token or "").encode()
    if not secrets.compare_digest(received_token, expected_token):
        raise HTTPException(status_code=401, detail="invalid callback token")
 
    payload = await request.json()
    task = payload["task"]
    # 建议将 task 写入队列或数据库后立即返回 2xx。
    return {"received": True, "task_id": task["id"]}

投递与重试规则

接收端返回任意 2xx 状态码即表示回调接收成功，响应体会被忽略。
网络异常、超时或非 2xx 响应会触发重试，重试间隔依次为 10、30、60、120、300 秒。
单次回调请求的超时时间为 10 秒。建议先持久化回调内容并快速返回 2xx，耗时业务放入异步队列处理。
平台不会跟随 3xx 重定向，避免将 X-Callback-Token 转发到未经授权的域名。
callback_url 必须解析到公网单播地址；回环地址、内网地址和带用户信息的 URL 不被接受。
某个中间状态重试耗尽不会阻止后续状态继续推送，终态回调仍会再次投递。
网络超时或不同内部阶段映射为同一公开状态时，接收端可能收到重复回调；请结合 task.id、task.status 和 task.updated_at 做幂等处理。

响应参数

名称	类型	描述	示例值
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` 或 `minimax-h3-lite`
task.status	String	任务状态，详见「任务状态」
task.error	Object	失败信息；失败时包含 `code` 和 `message`
task.created_at	Integer	任务创建时间，Unix 时间戳
task.updated_at	Integer	任务更新时间，Unix 时间戳
task.content.url	String	视频下载地址，仅成功任务返回
task.resolution	String	视频分辨率档位；终态返回实际交付档位，超分降级时为 `768P`
task.duration	Integer	视频时长，单位为秒
task.ratio	String	视频宽高比
task.task_type	String	固定为 `generation`
task.modality	String	固定为 `video`
task.estimated_remaining_seconds	Integer	预计距离任务完成还需等待的秒数；任务结束后返回 `0`
task.usage	Object	任务用量信息；不同状态下返回的子字段可能不同
task.usage.input_seconds	Integer	输入参考视频的总时长，多个视频先合计、再按秒向上取整
task.usage.input_image_count	Integer	输入图片数量，包含首帧、尾帧和参考图片
task.usage.use_context_ir	Boolean	该任务是否启用了 Context-IR 提示词优化
task.usage.total_seconds	Integer	成功任务的计费视频秒数，仅成功后返回
task.usage.output_seconds	Integer	成功任务的输出视频秒数，仅成功后返回

estimated_remaining_seconds 会随任务阶段动态更新，综合估算排队、提示词优化、视频生成、上传及超分等尚未完成阶段的耗时，仅供进度展示参考，不代表完成时限承诺。succeeded、failed 或 cancelled 等终态任务返回 0。

响应示例


{
  "task": {
    "id": "019xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1786686200,
    "updated_at": 1786686260,
    "content": {
      "url": "https://example.com/generated-video.mp4"
    },
    "resolution": "768P",
    "duration": 5,
    "usage": {
      "total_seconds": 5,
      "input_seconds": 0,
      "output_seconds": 5,
      "input_image_count": 0,
      "use_context_ir": false
    },
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video",
    "estimated_remaining_seconds": 0
  }
}

查询任务列表

分页查询当前公司下的 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-lite`	`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",
      "resolution": "768P",
      "duration": 5,
      "usage": {
        "input_seconds": 0,
        "input_image_count": 0,
        "use_context_ir": false,
        "total_seconds": 5,
        "output_seconds": 5
      },
      "ratio": "16:9",
      "task_type": "generation",
      "modality": "video",
      "estimated_remaining_seconds": 0
    }
  ],
  "total": 1
}

Skill 管理

Skill 用于保存可复用的镜头语言、叙事规则和提示词优化规范。Skill 不会单独生成视频；创建任务时传入 skill_id，并显式设置 use_context_ir=true 后，平台会在 Context-IR 阶段应用对应 Skill。

Skill 列表同时包含平台提供的官方 Skill 和当前账号创建的自定义 Skill：

official=true 表示官方 Skill，可查询和用于生成，但不能更新或删除。
official=false 表示当前账号的自定义 Skill，可更新或删除。

查询 Skill 列表


GET https://cp.compshare.cn/minimax/v2/skills

查询参数

名称	类型	必填	描述	示例值
page_num	Integer	否	页码，从 `1` 开始，默认 `1`	`1`
page_size	Integer	否	每页数量，默认 `20`，最大 `100`；超过 `100` 时按 `100` 处理	`20`
keyword	String	否	Skill 关键字，首尾空白会被忽略	`电影`

请求示例


curl -G 'https://cp.compshare.cn/minimax/v2/skills' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Accept: application/json' \
  --data-urlencode 'page_num=1' \
  --data-urlencode 'page_size=20' \
  --data-urlencode 'keyword=电影'

响应参数

名称	类型	描述
items	Array of Object	Skill 列表
items[].id	String	Skill ID；创建视频任务时作为 `skill_id` 传入
items[].name	String	Skill 名称
items[].description	String	Skill 简介；未设置时不返回
items[].content	String	Skill 的完整规则内容
items[].official	Boolean	是否为平台官方 Skill
items[].created_at	Integer	创建时间，Unix 秒级时间戳；无数据时不返回
items[].updated_at	Integer	最近更新时间，Unix 秒级时间戳；无数据时不返回
total	Integer	符合条件的 Skill 总数


{
  "items": [
    {
      "id": "official-cinematic-story",
      "name": "电影叙事",
      "description": "增强镜头连续性与电影感",
      "content": "按照时间线组织镜头，保持主体、场景和光线连续。",
      "official": true,
      "created_at": 1786686200,
      "updated_at": 1786686200
    }
  ],
  "total": 1
}

创建 Skill

创建当前账号可管理的自定义 Skill。


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

请求参数

名称	类型	必填	描述	示例值
name	String	是	Skill 名称	`产品广告镜头`
description	String	否	Skill 的简短用途说明	`保持产品外观和品牌色一致`
content	String	是	Skill 的完整规则内容，可使用多行文本或 Markdown	`主体外观必须保持一致，镜头运动平稳。`

请求头 Content-Type 必须为 application/json，请求体最大为 64 KiB。

请求示例


curl -X POST 'https://cp.compshare.cn/minimax/v2/skills' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "产品广告镜头",
    "description": "保持产品外观和品牌色一致",
    "content": "主体外观必须保持一致；镜头运动平稳；最后一秒保留品牌展示画面。"
  }'

响应示例

创建和更新接口均返回 skill 对象，其字段与 Skill 列表中的元素一致：


{
  "skill": {
    "id": "skill-019xxxxx",
    "name": "产品广告镜头",
    "description": "保持产品外观和品牌色一致",
    "content": "主体外观必须保持一致；镜头运动平稳；最后一秒保留品牌展示画面。",
    "official": false,
    "created_at": 1786686200,
    "updated_at": 1786686200
  }
}

更新 Skill

更新当前账号创建的自定义 Skill。请求体使用与创建接口相同的字段；更新时请传入完整的 name、description 和 content，未传入的字符串字段会按空值提交。


PUT https://cp.compshare.cn/minimax/v2/skills/{skill_id}

路径参数

名称	类型	必填	描述	示例值
skill_id	String	是	要更新的自定义 Skill ID	`skill-019xxxxx`

请求示例


curl -X PUT 'https://cp.compshare.cn/minimax/v2/skills/skill-019xxxxx' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "产品广告镜头 V2",
    "description": "保持产品外观、品牌色和文字清晰",
    "content": "主体外观必须保持一致；镜头运动平稳；品牌文字不能变形；最后一秒保留品牌展示画面。"
  }'

删除 Skill

删除当前账号创建的自定义 Skill。官方 Skill 不能删除。


DELETE https://cp.compshare.cn/minimax/v2/skills/{skill_id}

路径参数

名称	类型	必填	描述	示例值
skill_id	String	是	要删除的自定义 Skill ID	`skill-019xxxxx`

请求示例


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

响应示例


{
  "skill_id": "skill-019xxxxx"
}

查询积分套餐包

查询当前 API Key 所属账号已经领取或购买的 MiniMax H3 积分套餐包。该接口没有查询参数和请求体，结果按创建时间从新到旧排列。


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

请求示例


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

响应参数

名称	类型	描述
items	Array of Object	当前账号的积分套餐包列表
items[].id	String	套餐包唯一 ID
items[].code	String	套餐包规格编码
items[].name	String	套餐包名称
items[].status	String	套餐包状态：`pending`、`active`、`exhausted` 或 `expired`
items[].total_points	Integer	套餐包初始积分总额
items[].remaining_points	Integer	套餐包尚未实际扣减的积分，包含已预占积分
items[].reserved_points	Integer	已被进行中任务预占的积分
items[].available_points	Integer	当前可用于创建新任务的积分，等于 `remaining_points - reserved_points`；不可用状态下为 `0`
items[].purchased_at	Integer	套餐包购买或激活时间，Unix 秒级时间戳；尚未激活时不返回
items[].expires_at	Integer	套餐包过期时间，Unix 秒级时间戳；尚未激活时不返回
items[].created_at	Integer	套餐包记录创建时间，Unix 秒级时间戳
items[].order_no	String	购买订单号；免费套餐包或尚未生成订单时不返回
items[].total_price	Integer	实付金额，单位为分；无付费金额时不返回
total	Integer	返回的套餐包总数

响应示例


{
  "items": [
    {
      "id": "package-019xxxxx",
      "code": "points_1100",
      "name": "1100 积分包",
      "status": "active",
      "total_points": 1100,
      "remaining_points": 900,
      "reserved_points": 100,
      "available_points": 800,
      "purchased_at": 1786686200,
      "expires_at": 1818222200,
      "created_at": 1786686100,
      "order_no": "order-202608140001",
      "total_price": 940
    },
    {
      "id": "package-019yyyyy",
      "code": "points_free_300",
      "name": "300 免费积分包",
      "status": "exhausted",
      "total_points": 300,
      "remaining_points": 0,
      "reserved_points": 0,
      "available_points": 0,
      "purchased_at": 1784000000,
      "expires_at": 1815536000,
      "created_at": 1784000000
    }
  ],
  "total": 2
}

套餐包状态说明：

状态	描述
`pending`	订单尚未完成，套餐包暂不可用
`active`	套餐包已生效且仍有可用积分
`exhausted`	套餐包积分已经用完
`expired`	套餐包已经过期

remaining_points 包含已经预占但尚未结算的积分，因此判断能否创建新任务时应使用 available_points。例如剩余 900 积分、其中 100 积分已被任务预占时，实际可用积分为 800。

查询积分余额

查询当前 API Key 所属账号的 MiniMax H3 有效积分余额。该接口没有查询参数和请求体。


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

请求示例


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

响应参数

名称	类型	描述	示例值
total_points	Integer	有效积分总额，即所有未到期、已激活积分包的剩余积分总和；包含已预占积分	`1000`
reserved_points	Integer	已被任务预占、暂时不能用于创建新任务的积分	`150`
available_points	Integer	当前可用积分，等于 `total_points - reserved_points`，最低为 `0`	`850`


{
  "total_points": 1000,
  "reserved_points": 150,
  "available_points": 850
}

创建视频任务时会先预占预计消耗的积分。任务成功后，预占积分转为实际扣减；任务最终失败或取消后，预占积分会被释放。因此存在进行中的任务时，available_points 可能小于 total_points。

取消任务

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


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 30",
    "http_code": "400"
  },
  "request_id": "request-xxxx"
}

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


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

MiniMax H3 视频任务 API

接入信息

请求地址

身份认证

获取 API Key

推荐调用流程

创建视频任务

请求头

请求参数

分辨率参数

content 元素结构

素材类型与 role

素材地址与文件大小

文生视频示例

首帧生视频示例

使用 Skill 生成无声视频

状态回调

带回调的创建示例

平台发出的回调请求

接收端 Token 校验示例

投递与重试规则

响应参数

查询单个任务

路径参数

请求示例

响应参数

响应示例

查询任务列表

查询参数

请求示例

响应参数

Skill 管理

查询 Skill 列表

查询参数

请求示例

响应参数

创建 Skill

请求参数

请求示例

响应示例

更新 Skill

路径参数

请求示例

删除 Skill

路径参数

请求示例

响应示例

查询积分套餐包

请求示例

响应参数

响应示例

查询积分余额

请求示例

响应参数

取消任务

路径参数

请求示例

响应参数

任务状态

错误响应