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

注意： MiniMax H3 视频、Qwen-Image 图片生成和 IndexTTS 2.5 语音 API 都使用 MiniMax H3 模块专属的 API Key（以 sk-ml- 开头），需在视频工作台中单独创建。优云智算控制台的其他 API 密钥或模型服务 API Key 不能用于这些接口，否则会返回 401 和 {"error":"invalid 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`；开启后先整理和优化生成要求，再生成视频。H3 对提示词质量较敏感，所有生成时长均强烈建议设置为 `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。

4～30 秒均一次生成，包括带参考视频的任务。 无需为了长视频设置分段标记、拆分提示词或填写固定时间轴格式。

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 再缩小，也不会进入超分队列。

开启 use_context_ir 时，每条任务另收 5 积分。提供参考视频时，480P 的输入费率为 5 积分/s，768P、1080P、2K、4K 的输入费率为 10 积分/s。参考视频先合计时长，再向上取整到整秒计费。参考图片和音频不额外收费。计费示例见积分与计费。

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` 时填写。纯文生视频必须包含非空文本；所有文本合并后最多 10000 个 Unicode 字符	`一只猫在海边奔跑`
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	2–15.08 秒	不超过 15.08 秒	会规范为 MP4/H.264、24 FPS，短边最大 720 像素
参考音频	15 MiB	2–15.08 秒	不超过 15.08 秒	保留原始音频并转存

首帧、尾帧和参考图片的宽、高均须在 256～5760 像素，宽高比（宽 ÷ 高）须在 2:5～5:2（0.4～2.5），范围均包含边界。

时长范围包含边界，每段参考视频和每段参考音频都必须至少 2 秒，不能用多段不足 2 秒的素材相加满足下限。视频与音频分别累计时长。这些限制针对输入参考素材，与输出视频的 duration 分开计算。

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

30 秒参考视频示例

以下请求使用参考视频生成 30 秒视频，关闭提示词优化。将 JSON 作为创建视频任务接口的请求体提交；提示词无需拆段。


{
  "model": "MiniMax-H3",
  "content": [
    {"type": "text", "text": "参考 <Video 1> 的运镜节奏，生成海边公路上的汽车行驶画面，镜头从远景逐渐靠近，最后跟随汽车驶向夕阳。"},
    {"type": "video_url", "video_url": {"url": "https://example.com/reference.mp4"}, "role": "reference_video"}
  ],
  "resolution": "768P",
  "duration": 30,
  "ratio": "16:9",
  "use_context_ir": false
}

仅参考音频示例

以下请求仅使用音频素材，画面由提示词描述，无需额外提供图片或视频。参考音频仍须满足前述单段及合计时长限制。


{
  "model": "MiniMax-H3",
  "content": [
    {"type": "text", "text": "清晨的海边，一名旅人沿海岸缓步前行，镜头平稳跟拍。参考 <Audio 1> 的海浪与风声质感生成自然环境声，无对白，无背景音乐。"},
    {"type": "audio_url", "audio_url": {"url": "https://example.com/ocean.wav"}, "role": "reference_audio"}
  ],
  "resolution": "768P",
  "duration": 30,
  "ratio": "16:9",
  "use_context_ir": false
}

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

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

示例素材	对应标签	提供的信息
`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 请求。创建成功后会推送当前状态，可能是 moderating 或 queued 等进行中状态；任务成功时，回调结果中的 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 做幂等处理。
轮询或回调不保证覆盖每一个中间阶段；请以最新查询结果为准，并在收到 succeeded、failed、cancelled 或 blocked 时结束等待。

响应参数

名称	类型	描述	示例值
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	预计剩余秒数；`-1` 表示排队中、暂无法可靠估算，终态返回 `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 会随任务阶段动态更新，仅供进度展示参考，不代表完成时限承诺。排队阶段可能返回 -1，表示暂无法可靠估算；执行超过预估时间时也可能返回 0，任务仍在继续。只有 task.status 为 succeeded、failed、cancelled 或 blocked 才表示任务结束。

响应示例


{
  "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，传入该参数会返回参数错误。

filter.status 当前仅接受表中的五个值。查询结果还可能返回 scheduled、moderating 和 blocked，但这些值不能作为筛选参数，否则会返回 400 参数错误。需要查找这些任务时，省略 filter.status 后分页查询，或按任务 ID 调用单个任务查询接口。filter.status=failed 不包含 blocked。

请求示例


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	Number	套餐包尚未实际扣减的积分，包含已预占积分，最多两位小数
items[].reserved_points	Number	已被进行中任务预占的积分，最多两位小数
items[].available_points	Number	当前可用于创建新任务的积分，等于 `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。

积分包由同组织的视频、生图和音频任务共用。音频开启精确计费后，剩余、预占和可用积分可能包含两位小数；例如剩余 99.67、预占 0.33 时，可用积分为 99.34。这些字段仍是 JSON 数字，整数响应也继续有效；客户端应支持小数，不能截断成整数。

查询积分余额

查询当前 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	Number	有效积分总额，即所有未到期、已激活积分包的剩余积分总和；包含已预占积分，最多两位小数	`1000`
reserved_points	Number	已被任务预占、暂时不能用于创建新任务的积分，最多两位小数	`150`
available_points	Number	当前可用积分，等于 `total_points - reserved_points`，最低为 `0`，最多两位小数	`850`


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

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

该余额与同组织的音频、生图任务共享。以下是存在小数消费及预占时的响应示例：


{
  "total_points": 99.67,
  "reserved_points": 0.33,
  "available_points": 99.34
}

余额支持小数不改变视频任务的计价规则。接口路径、字段名和单位保持不变；对金额进行比较或汇总时，建议使用十进制定点类型或整数最小单位。

取消任务

取消仍允许取消的视频任务。支持待开始、内容审核、提示词优化排队和视频生成排队阶段；提示词优化中、视频生成中（含执行节点已领取或正在上传结果）和超分中不支持取消。该操作不会物理删除任务历史记录。

后置超分排队时也可以调用此接口，但此时原生视频已经生成：操作会跳过超分、交付原生 768P 视频，返回 succeeded 并释放超分加价部分，基础生成积分照常扣除。


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`，跳过后置超分返回 `succeeded`	`cancelled`


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

若任务已进入不支持取消的阶段，接口会返回业务错误“只有排队中的任务才允许取消”；这不表示取消请求已受理。状态可能在查询与取消之间变化，操作后请重新查询任务，按实际返回状态处理。

任务状态

单任务查询、任务列表和回调中的 task.status（列表中为 items[].status）可能返回以下状态：

状态	是否终态	含义与处理方式
`scheduled`	否	预约任务待开始；同公司下在控制台创建的预约任务也可能出现在查询结果中。当前视频创建 API 不提供预约参数
`moderating`	否	输入内容等待审核或正在审核，继续等待；尚未开始视频生成
`queued`	否	提示词优化排队或视频生成排队，继续等待
`running`	否	提示词优化、视频生成、结果上传、后置超分排队或超分执行中，继续等待；不代表原片和超分均已完成
`succeeded`	是	已交付视频；调用单任务查询获取 `task.content.url`，并核对 `resolution` 的实际交付档位
`failed`	是	审核服务处理、提示词优化或视频生成等阶段最终失败；查看 `task.error.message`，预占积分会释放
`cancelled`	是	任务已取消，预占积分会释放
`blocked`	是	输入内容未通过平台内容审核，任务停止且不交付视频，预占积分会释放；查看 `task.error.message`，调整内容后再创建任务

API 会合并部分处理阶段。控制台中的“内容审核排队中”和“内容审核中”都对应 moderating；“提示词优化排队”和“视频生成排队”都对应 queued；“提示词优化中”“视频生成中”“超分排队”和“超分中”都对应 running。阶段详情见视频任务状态说明；本 API 响应不提供控制台接口的 Stage 字段。

状态流转

未启用提示词优化时，典型流程为：


moderating → queued → running → succeeded

启用 use_context_ir=true 后，提示词优化完成还需要进入视频生成队列，因此可能观察到：


moderating → queued（提示词优化排队）→ running（提示词优化中）
           → queued（视频生成排队）→ running（生成、上传及可选超分）→ succeeded

预约任务先处于 scheduled，到达开始时间后再进入后续流程。适用免审规则的任务会跳过审核阶段。轮询可能跳过短暂的中间状态；自动重试也可能让任务从 running 回到 queued，这不表示任务已失败或创建了新任务。

审核不通过时结束为 blocked；处理最终失败时结束为 failed；在允许取消的阶段取消后结束为 cancelled。后置超分失败或在超分排队时被跳过，只要原片可交付，任务仍为 succeeded，实际 resolution 返回 768P，并释放超分加价部分。

轮询与结果处理

创建成功仅表示任务已受理。保存 task_id，定期查询或等待回调。
遇到 scheduled、moderating、queued、running 时继续等待。不要把 running → queued、预计剩余时间为 0 或暂未返回 content.url 当成失败或完成。
遇到 succeeded、failed、cancelled、blocked 时停止轮询。成功后通过单任务查询获取下载地址；失败或审核未通过时读取 task.error.message。列表接口不附带下载地址。

task.error.code 当前使用 generation_failed，审核未通过也可能使用该值；区分任务失败和审核拦截应读取 task.status。查询请求本身返回 HTTP 或业务错误时，应按错误响应处理，不能据此直接把任务判为 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

素材地址与文件大小

参考素材的提示词写法

素材标签与编号

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

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

文生视频示例

首帧生视频示例

30 秒参考视频示例

仅参考音频示例

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

使用 Skill 生成无声视频

状态回调

带回调的创建示例

平台发出的回调请求

接收端 Token 校验示例

投递与重试规则

响应参数

查询单个任务

路径参数

请求示例

响应参数

响应示例

查询任务列表

查询参数

请求示例

响应参数

Skill 管理

查询 Skill 列表

查询参数

请求示例

响应参数

创建 Skill

请求参数

请求示例

响应示例

更新 Skill

路径参数

请求示例

删除 Skill

路径参数

请求示例

响应示例

查询积分套餐包

请求示例

响应参数

响应示例

查询积分余额

请求示例

响应参数

取消任务

路径参数

请求示例

响应参数

任务状态

状态流转

轮询与结果处理

错误响应