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	否	输出分辨率档位，支持 `480P`、`768P`、`1080P`、`2K`、`4K`，默认 `768P`，区分大小写	`480P`
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 建议明确填写下列五个值之一：

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

480P 支持文生视频、首尾帧视频和全能参考视频三种创建方式。它是 MiniMax H3 直接生成的原生规格，不会先生成 768P 再缩小，也不会进入超分队列。

480P 输出尺寸

选择 480P 时，ratio 会映射到以下原生输出尺寸：

ratio	输出尺寸（宽 × 高）
`21:9`	`1120 × 480`
`16:9`	`864 × 480`
`4:3`	`640 × 480`
`1:1`	`480 × 480`
`3:4`	`480 × 640`
`9:16`	`480 × 864`

当 ratio=adaptive 且请求包含图片素材时，系统会根据首帧、尾帧或第一张参考图的宽高比，选择最接近的 480P 原生尺寸；没有可用于判断比例的图片时，按默认 16:9 输出 864 × 480。

例如，生成原生 480P 视频时传入：


{
  "resolution": "480P"
}

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


{
  "resolution": "1080P"
}


{
  "resolution": "2K"
}


{
  "resolution": "4K"
}

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

1080P、2K 和 4K 通过后置超分生成，实际输出宽高会根据 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。

参考素材的提示词写法

参考素材通过 content 中的媒体元素传入，生成要求写在 type=text 的 text 中。role 用于区分素材类型；具体参考哪些特征、保留哪些内容、如何组合素材，需要在提示词中说明。

素材标签与编号

素材	提示词标签	对应关系
参考图片	`<Picture 1>`、`<Picture 2>`	按 `content` 中 `role=reference_image` 的图片出现顺序编号
参考视频	`<Video 1>`、`<Video 2>`	按 `content` 中 `type=video_url` 的视频出现顺序编号
参考音频	`<Audio 1>`、`<Audio 2>`	按 `content` 中 `type=audio_url` 的音频出现顺序编号

三类素材各自从 1 开始编号，文本元素不占编号。例如依次传入人物图、视频、产品图、音频时，分别对应 <Picture 1>、<Video 1>、<Picture 2>、<Audio 1>。增删或调整同类素材顺序后，应同步修改提示词中的编号。

标签保留英文大小写、半角尖括号和数字前的空格，例如 <Picture 1>。
图片使用 <Picture N>。接口不会将 @图片1、图片1、<Image 1> 或文件名自动转换为素材标签。
标签必须对应实际传入的素材；只在文本里写标签或 URL，不会自动加载素材。
全能参考模式下，图片必须显式填写 "role": "reference_image"。省略图片 role 会按首帧处理，不能与参考素材混用。

参考视频：指定动作、运镜与节奏

参考视频以连续画面参与生成，可以提供动作变化、镜头运动、剪辑顺序和时间节奏，也可以作为人物、物体、场景或风格的来源。MP4/H.264、24 FPS 和短边最大 720 像素的预处理用于统一输入规格，不会自动将视频变成只含动作的素材。

可以在提示词中明确限定只参考动作、运镜和节奏，并由图片定义人物与产品，例如：


人物外观、发型和服装以 <Picture 1> 为准，产品外形、颜色和材质以 <Picture 2> 为准。
<Video 1> 仅提供人物动作、镜头运动和时间节奏；不要沿用其中人物的身份、外观或原有产品。
将参考动作应用到 <Picture 1> 的人物和 <Picture 2> 的产品上。

这些要求通过提示词引导模型，不是独立的动作提取或人物替换开关，不能保证逐帧复现或完全隔离其他视觉特征。素材中的动作应与目标人物、产品形态及输出时长相匹配。

参考视频带有音轨时，平台会保留音轨并送入模型。只需要视觉动作参考时，建议上传已移除音轨的视频；需要明确指定声音来源时，另行通过 audio_url 提交，并使用 <Audio N> 描述其用途。mute_audio=true 会移除最终成片的全部音轨，不能用来仅忽略参考视频的声音。

参考音频：音色、内容、音乐与环境声

参考音频可以用于以下生成要求。请明确区分“沿用原声音内容”和“只参考声音特征、生成新内容”。这些用途符合 MiniMax H3 官方参考模式提示词指南中的音频参考关系。

用途	提示词示例
音色与表达方式参考	`人物的音色、语速和表达方式参考 <Audio 1>，台词使用本提示词提供的新文案。`
BGM、节拍、环境声或音效参考	`背景音乐参考 <Audio 1> 的风格与节奏；环境声参考 <Audio 2>，保持对白清晰。`
原有人物语音与内容参考	`沿用 <Audio 1> 中的对白内容与声音特征，由 <Picture 1> 中的人物说出，并保持口型同步。`
参考音色说新台词并同步口型	`<Picture 1> 中的人物参考 <Audio 1> 的音色说：“让每一次出发，都更轻松。”不要复述音频原台词，口型与新对白同步。`

“参考音色 + 新台词 + 口型同步”可以在同一个视频生成任务中表达：同时提交人物图片和参考音频，在提示词中指定说话人、新台词、语言及口型要求。人物、产品和动作参考可以继续按需组合，见下方完整示例。

参考音频参与 H3 的音画联合生成，成片声音由模型生成。音色参考不等同于保证精确复刻的声音克隆；即使要求沿用原对白，也不保证原始音轨逐采样不变或口型完全一致。建议使用清晰、单人、少背景音乐的语音素材，并为完整台词预留足够时长。需要保留生成的对白时，省略 mute_audio 或设置为 false。

文生视频示例


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
  }'

全能参考示例：人物图、产品图、视频、音频与新台词

以下请求生成一段人物展示产品并口播新文案的视频。素材分工如下，也可替换为其他人物、物体和场景：

示例素材	对应标签	提供的信息
`person.jpg`	`<Picture 1>`	人物外观、发型与服装
`product.jpg`	`<Picture 2>`	产品外形、颜色与材质
`motion-silent.mp4`	`<Video 1>`	动作、镜头运动与节奏；示例使用无音轨视频
`voice.mp3`	`<Audio 1>`	说话音色与表达方式
`text` 中的新台词	不分配素材编号	实际需要人物说出的内容

将下面 JSON 保存为 request.json，把示例 URL 替换为可直接访问的实际素材地址。示例将提示词拆成多个 text 元素便于阅读，接口会按顺序以换行拼接；也可以合并为一个 text 元素。


{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "生成一段 10 秒的写实产品展示视频。主角以 <Picture 1> 为人物参考，保持面容、发型和服装一致；手中产品以 <Picture 2> 为参考，保持外形、颜色和材质一致。场景为光线柔和、背景简洁的室内。"
    },
    {
      "type": "text",
      "text": "<Video 1> 仅用于参考人物展示动作、镜头运动和时间节奏，不要沿用视频中的人物身份、外观、原有产品或声音。将动作应用到上述人物与产品，并适配 10 秒输出时长。"
    },
    {
      "type": "text",
      "text": "主角参考 <Audio 1> 的音色与自然表达方式，用普通话说出新台词：<d>[Chinese] 让每一次出发，都更轻松。</d> 不要复述参考音频中的原台词，口型与新对白同步；对白结束后闭嘴并自然微笑。"
    },
    {
      "type": "text",
      "text": "0 至 2 秒展示人物与产品；2 至 8 秒人物面向镜头完成上述口播并轻抬产品，嘴部保持清晰可见；8 至 10 秒保持产品展示姿态。保留轻微室内环境声，不添加背景音乐、旁白或字幕。"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/person.jpg" },
      "role": "reference_image"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/product.jpg" },
      "role": "reference_image"
    },
    {
      "type": "video_url",
      "video_url": { "url": "https://example.com/motion-silent.mp4" },
      "role": "reference_video"
    },
    {
      "type": "audio_url",
      "audio_url": { "url": "https://example.com/voice.mp3" },
      "role": "reference_audio"
    }
  ],
  "resolution": "768P",
  "duration": 10,
  "ratio": "9:16",
  "use_context_ir": true,
  "mute_audio": false
}


curl -X POST 'https://cp.compshare.cn/minimax/v2/video_generation' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  --data-binary @request.json

本例显式启用 use_context_ir，由提示词优化阶段整理素材关系与生成要求；该开关不是启用参考素材的必要条件。新台词写在 text 中，<d>[Chinese] ...</d> 用于标记中文对白，不需要额外添加 voice_id 或 lip_sync 等请求字段。修改台词长度时，请同时调整提示词时间安排和 duration。

使用 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	视频分辨率档位；原生输出返回 `480P` 或 `768P`，超分降级时返回 `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

推荐调用流程

创建视频任务

请求头

请求参数

分辨率参数

480P 输出尺寸

content 元素结构

素材类型与 role

素材地址与文件大小

参考素材的提示词写法

素材标签与编号

参考视频：指定动作、运镜与节奏

参考音频：音色、内容、音乐与环境声

文生视频示例

首帧生视频示例

全能参考示例：人物图、产品图、视频、音频与新台词

使用 Skill 生成无声视频

状态回调

带回调的创建示例

平台发出的回调请求

接收端 Token 校验示例

投递与重试规则

响应参数

查询单个任务

路径参数

请求示例

响应参数

响应示例

查询任务列表

查询参数

请求示例

响应参数

Skill 管理

查询 Skill 列表

查询参数

请求示例

响应参数

创建 Skill

请求参数

请求示例

响应示例

更新 Skill

路径参数

请求示例

删除 Skill

路径参数

请求示例

响应示例

查询积分套餐包

请求示例

响应参数

响应示例

查询积分余额

请求示例

响应参数

取消任务

路径参数

请求示例

响应参数

任务状态

错误响应