MiniMax H3 视频生成 OpenAPI 用户接入指南

2026/8/31

本文面向通过服务端程序调用 MiniMax H3 视频生成能力的第三方开发者。接入时以本指南列出的接口、字段、响应模型和错误码为准。

1. 开通流程

调用 API 前需要：

注册并登录千里云平台账号。
在控制台购买积分套餐，确认账号有可用积分。
进入 MiniMax H3 的 API Key 页面创建 API Key。
将完整 API Key 保存到调用方服务端的安全配置或密钥管理系统中。

一个账号最多保留 3 个有效 API Key。多个 Key 共享账号积分余额，任务仍按创建任务时使用的 API Key 归因。

完整 Key 形如：

sk-qly-<43位Base64URL无填充随机串>

API Key 只能放在服务端。不要写入浏览器代码、HTML、URL、Query、请求 Body、日志、异常信息或代码仓库。

2. API 地址和认证

生产环境 API 基础地址为：

<https://ai-media-api.qianlicloud.com/api/minimax/v1>

下文接口路径均相对于该基础地址。

所有接口都必须携带：

Authorization: Bearer <YOUR_API_KEY>

认证失败统一返回 HTTP 401 和 INVALID_API_KEY。

3. 接口总览

功能	方法	路径
创建视频任务	`POST`	`/tasks`
查询单个任务	`GET`	`/tasks/{taskId}`
查询任务列表	`GET`	`/tasks`
查询积分余额	`GET`	`/quota/summary`
取消任务	`POST`	`/tasks/{taskId}/cancel`

一次创建请求只创建一个独立 Task，并生成一个视频。需要生成多个视频时，请使用不同的 Idempotency-Key 分别创建多个任务。

4. 创建视频任务

请求地址

POST /api/minimax/v1/tasks

请求头

参数	类型	是否必填	说明
`Authorization`	String	是	`Bearer <YOUR_API_KEY>`。
`Content-Type`	String	是	固定为 `application/json`。
`Idempotency-Key`	String	是	本次创建请求的唯一幂等键，长度为 1～128 个 Unicode 字符。

请求参数

参数	类型	是否必填	说明
`model`	String	是	固定为 `MiniMax-H3`。
`content`	Array	是	文本和参考素材列表，包含 2～32 项；至少包含一个非空 `text` 项和一个图片、视频或音频项，媒体项总数不超过 12 个。
`resolution`	String	否	输出视频分辨率档位。当前公开接口仅支持 `768P`，默认 `768P`；`480P` 和 `1080P` 当前不能通过本接口提交。
`duration`	Integer	否	输出视频目标时长，必须是 `4`～`15` 的整数秒，默认 `8`。这是生成结果的目标时长，不是参考素材时长。
`ratio`	String	否	`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`9:16`、`16:9`，默认 `9:16`。
`production_prior`	String	否	`off`、`low`、`medium`、`high`，默认 `medium`。
`aigc_watermark`	Boolean	否	当前只能为 `false`。
`seed`	Integer	否	`0`～`4294967295` 的整数；不传时由服务端随机生成。
`callback_url`	String	否	HTTPS 回调地址，必须通过服务端安全校验。

内容元素结构

元素类型	必填字段	说明
`text`	`text`	文本提示词。多个文本项会按出现顺序合并，合并后最多 7000 个 Unicode code points。
`image_url`	`image_url.url`	图片素材地址。最多 9 个。
`video_url`	`video_url.url`	MP4 视频素材地址。最多 3 个，所有参考视频总时长不超过 15 秒。
`audio_url`	`audio_url.url`	音频素材地址。最多 3 个，不能单独使用，必须同时提供图片或视频素材。

素材限制

素材类型	数量限制	单个文件大小	时长限制	支持格式
图片	0～9 张	单个不超过 30 MiB	图片没有时长限制	PNG、JPEG、WebP、HEIC、HEIF
视频	0～3 个	单个不超过 50 MiB	所有参考视频总时长不超过 15 秒	MP4
音频	0～3 个	单个不超过 15 MiB	创建请求层当前不对音频时长做业务限制；素材媒体校验仍可能拒绝无法解析或不符合执行要求的音频	WAV、MP3

全部媒体数量不超过 12 个。每次请求至少需要一个图片、视频或音频素材；音频不能单独使用，必须与图片或视频同时提交。参考素材 URL 必须是服务端可访问的 HTTPS 地址，URL 长度不超过 2048 个字符。

服务端会先下载并识别远程素材，再以可信媒体信息校验文件大小、实际格式和参考视频时长；校验失败时不会继续创建任务或预占积分。所有参考视频的总时长超过 15 秒时，请先裁剪后重试。图片没有时长概念；创建请求层当前不对音频时长做业务限制，但无法解析、损坏或不符合执行要求的音频仍可能在素材校验或任务执行阶段失败。

参考视频计费时按实际媒体时长向下取整到整秒；这只影响报价和积分计算，不改变输出视频的 duration 取值规则。文件大小中的 MiB 按 × 字节计算。

提示词与素材引用

素材编号按素材类型分别从 1 开始计数，编号取决于该类型素材在 content 中的出现顺序，不按所有内容项的全局位置计数。

引用格式	对应素材
`图1`、`图2`……	第 1、2……个 `image_url` 素材
`视频1`、`视频2`……	第 1、2……个 `video_url` 素材
`音频1`、`音频2`……	第 1、2……个 `audio_url` 素材

使用规则：

content 中的多个 text 项会按出现顺序合并为提示词，各文本项之间以换行分隔。
任意 text 项都可以引用本次请求中的素材，文本项和素材项在 content 中可以交错排列。
引用编号必须从 1 开始，且不能超过对应类型实际提交的素材数量；未提交的素材可以不被引用。
同一个素材可以在提示词中被多次引用，也不要求所有素材都必须被引用。
图N 只能引用图片，视频N 只能引用视频，音频N 只能引用音频；引用不存在的编号返回 INVALID_PROMPT_REFERENCE。
提示词至少包含一个非空文本项，合并后的文本不超过 7000 个 Unicode code points。

素材编号只由对应类型的素材项决定，不受提示词中引用文字出现的位置影响。例如，content 中先出现一个视频、再出现两张图片时，图片仍编号为 图1、图2，视频仍编号为 视频1。如果文本中写了 图3 但本次请求只提交两张图片，请求会被拒绝。

请求示例

{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "让图1中的主体沿视频1的运动方向移动，并根据音频1的节奏切换镜头"
    },
    {
      "type": "image_url",
      "image_url": {"url": "https://media.example.com/reference/person.png"}
    },
    {
      "type": "video_url",
      "video_url": {"url": "https://media.example.com/reference/motion.mp4"}
    },
    {
      "type": "audio_url",
      "audio_url": {"url": "https://media.example.com/reference/music.mp3"}
    }
  ],
  "resolution": "768P",
  "duration": 8,
  "ratio": "9:16",
  "production_prior": "medium",
  "aigc_watermark": false,
  "seed": 100
}

响应参数

参数	类型	说明
`task_id`	String	任务唯一标识。
`status`	String	任务状态，初始通常为 `QUEUED`。
`status_url`	String	查询当前任务详情的相对路径。
`created_at`	String	任务创建时间，ISO-8601 格式。
`progress`	Object	任务进度，包含 `percent`、`stage`、`generation_elapsed_seconds`、`updated_at`。
`generations`	Array	本次任务生成结果列表。
`generations[].generation_id`	String	生成记录唯一标识。
`generations[].index`	Integer	生成记录序号。
`generations[].status`	String	生成记录状态。
`generations[].outputs`	Array	输出视频列表，成功后可获取视频地址。
`quota`	Object	本次任务的积分信息。
`quota.quota_type`	String	固定为 `AI_VIDEO_UNIT`。
`quota.single_generation_units`	Integer	单条视频预估消耗积分。
`quota.total_units`	Integer	本次任务预估消耗总积分。
`trace_id`	String	请求追踪标识。

响应示例

{
  "code": "OK",
  "message": "OK",
  "data": {
    "task_id": "task_01JEXAMPLE",
    "status": "QUEUED",
    "status_url": "/api/minimax/v1/tasks/task_01JEXAMPLE",
    "created_at": "2026-08-26T10:00:00Z",
    "progress": {
      "percent": 1,
      "stage": "QUEUED",
      "updated_at": "2026-08-26T10:00:00Z"
    },
    "generations": [{
      "generation_id": "generation_01JEXAMPLE_1",
      "index": 1,
      "status": "QUEUED",
      "outputs": []
    }],
    "quota": {
      "quota_type": "AI_VIDEO_UNIT",
      "single_generation_units": 480,
      "total_units": 480
    }
  },
  "trace_id": "trace_01JEXAMPLE"
}

4.1 读取任务进度

创建响应、任务列表项和任务详情都包含 progress 对象。该值用于表示任务执行进度，请以接口返回结果为准。

字段	说明
`percent`	`0～100` 的整数。排队新任务从 `1` 开始，只有 `SUCCEEDED` 为 `100`；失败或取消保留最后可知值或 `0`。
`stage`	`QUEUED`、`PREPARING`、`SUBMITTING`、`GENERATING`、`FINALIZING`、`UPLOADING`、`RETRYING`、`SUCCEEDED`、`FAILED`、`CANCELLED`。
`generation_elapsed_seconds`	实际生成耗时，从首次进入 `GENERATING` 到当前或终态计算，不包含排队、素材准备和提交时间；尚未开始生成时可能为空。
`updated_at`	进度投影的最近更新时间，可能为空。

进度阶段包括排队、准备、提交、生成、处理和上传等阶段，百分比用于辅助展示，不代表严格线性完成比例。

建议在任务状态为 QUEUED 或 RUNNING 时轮询列表或详情，直接使用接口返回的 progress；进入 SUCCEEDED、FAILED 或 CANCELLED 状态后停止轮询。

任务状态

字段	当前状态值	说明
`data.status`	`QUEUED`、`RUNNING`、`SUCCEEDED`、`PARTIAL_SUCCEEDED`、`FAILED`、`CANCELLED`	Task 聚合状态。第三方新任务固定只有一个 Generation，正常不会产生 `PARTIAL_SUCCEEDED`。
`data.generations[].status`	`CREATED`、`VALIDATED`、`QUEUED`、`RUNNING`、`SUCCEEDED`、`FAILED`、`CANCELLED`、`REJECTED`、`EXPIRED`	单条 Generation 的执行状态；通常从 `QUEUED` 开始。
`data.progress.stage`	`QUEUED`、`PREPARING`、`SUBMITTING`、`GENERATING`、`FINALIZING`、`UPLOADING`、`RETRYING`、`SUCCEEDED`、`FAILED`、`CANCELLED`	当前执行阶段，用于进度展示，不等同于 Task 状态。

新建第三方任务只会创建一个 Generation，因此调用方通常按 QUEUED、RUNNING、SUCCEEDED、FAILED、CANCELLED 处理；其他值用于兼容当前任务模型中的异常或历史状态。

创建幂等

Idempotency-Key 是创建接口的必填 Header，长度为 1～128 个 Unicode 字符。

同一 API Key 使用相同 Idempotency-Key 重试，会返回原任务，不重复创建和预占积分。
同一个 Key 必须对应同一组业务参数。
网络超时或收到 TASK_CREATION_STATUS_UNKNOWN 时，必须使用原 Idempotency-Key 重试。
新业务请求必须生成新的 Idempotency-Key。

5. 查询单个任务

请求地址

GET /api/minimax/v1/tasks/{taskId}

请求头

参数	类型	是否必填	说明
`Authorization`	String	是	`Bearer <YOUR_API_KEY>`。

路径参数

参数	类型	是否必填	说明
`taskId`	String	是	创建视频任务后返回的任务唯一标识。

请求示例

GET /api/minimax/v1/tasks/task_01JEXAMPLE
Authorization: Bearer <YOUR_API_KEY>

响应参数

参数	类型	说明
`task_id`	String	任务唯一标识。
`status`	String	`QUEUED`、`RUNNING`、`SUCCEEDED`、`PARTIAL_SUCCEEDED`、`FAILED` 或 `CANCELLED`。
`created_at`	String	任务创建时间，ISO-8601 格式。
`updated_at`	String	任务最近更新时间。
`progress`	Object	当前任务进度。
`progress.percent`	Integer	`0`～`100` 的整数。
`progress.stage`	String	当前执行阶段。
`progress.generation_elapsed_seconds`	Integer	实际生成耗时，尚未开始生成时可能为空。
`progress.updated_at`	String	进度最近更新时间。
`generations`	Array	生成记录列表。
`generations[].generation_id`	String	生成记录唯一标识。
`generations[].index`	Integer	生成记录序号。
`generations[].status`	String	生成记录状态。
`generations[].outputs`	Array	输出视频列表。
`generations[].outputs[].url`	String	输出视频地址，生成成功后返回。
`generations[].outputs[].mime_type`	String	输出视频 MIME 类型。
`generations[].outputs[].size_bytes`	Integer	输出文件大小，单位为字节。
`generations[].outputs[].width`	Integer	视频宽度，单位为像素。
`generations[].outputs[].height`	Integer	视频高度，单位为像素。
`generations[].outputs[].duration_seconds`	Number	视频时长，单位为秒。
`generations[].outputs[].fps`	Number	视频帧率。
`generations[].outputs[].format`	String	视频格式。
`quota`	Object	本次任务的积分信息。
`quota.total_units`	Integer	本次任务预估消耗总积分。
`error`	Object	任务失败时的错误信息。
`error.code`	String	稳定错误码。
`error.message`	String	错误说明。
`trace_id`	String	请求追踪标识。

响应示例

{
  "code": "OK",
  "message": "OK",
  "data": {
    "task_id": "task_01JEXAMPLE",
    "status": "SUCCEEDED",
    "status_url": "/api/minimax/v1/tasks/task_01JEXAMPLE",
    "created_at": "2026-08-26T10:00:00Z",
    "updated_at": "2026-08-26T10:06:30Z",
    "progress": {
      "percent": 100,
      "stage": "SUCCEEDED",
      "generation_elapsed_seconds": 362,
      "updated_at": "2026-08-26T10:06:30Z"
    },
    "generations": [{
      "generation_id": "generation_01JEXAMPLE_1",
      "index": 1,
      "status": "SUCCEEDED",
      "outputs": [{
        "output_id": "output_01JEXAMPLE",
        "type": "video",
        "url": "https://media.example.com/output/video.mp4",
        "mime_type": "video/mp4",
        "size_bytes": 5242880,
        "width": 768,
        "height": 1365,
        "duration_seconds": 8,
        "fps": 25,
        "format": "mp4"
      }]
    }],
    "quota": {
      "quota_type": "AI_VIDEO_UNIT",
      "total_units": 480
    }
  },
  "trace_id": "trace_01JEXAMPLE"
}

任务不存在或不属于当前 API Key 时返回 HTTP 404、TASK_NOT_FOUND。

6. 查询任务列表

请求地址

GET /api/minimax/v1/tasks

请求头

参数	类型	是否必填	说明
`Authorization`	String	是	`Bearer <YOUR_API_KEY>`。

查询参数

参数	类型	是否必填	说明
`page`	Integer	否	页码，从 `1` 开始，默认 `1`。
`page_size`	Integer	否	每页数量，范围 `1`～`100`，默认 `20`。
`status`	String	否	按任务状态筛选。
`start_time`	String	否	创建时间起点，ISO-8601 UTC 格式。
`end_time`	String	否	创建时间终点，ISO-8601 UTC 格式。

请求示例

GET /api/minimax/v1/tasks?page=1&page_size=20&status=SUCCEEDED
Authorization: Bearer <YOUR_API_KEY>

响应参数

参数	类型	说明
`items`	Array	当前页任务列表，按创建时间倒序返回。
`items[].task_id`	String	任务唯一标识。
`items[].status`	String	任务状态。
`items[].status_url`	String	查询当前任务详情的相对路径。
`items[].created_at`	String	任务创建时间。
`items[].progress`	Object	当前任务进度。
`items[].progress.percent`	Integer	`0`～`100` 的整数。
`items[].progress.stage`	String	当前执行阶段。
`items[].progress.generation_elapsed_seconds`	Integer	实际生成耗时，尚未开始生成时可能为空。
`items[].progress.updated_at`	String	进度最近更新时间。
`items[].quota`	Object	本次任务的积分信息。
`items[].quota.total_units`	Integer	本次任务预估消耗总积分。
`total`	Integer	符合筛选条件的任务总数。
`page`	Integer	当前页码。
`page_size`	Integer	每页数量。

响应示例

{
  "code": "OK",
  "message": "OK",
  "data": {
    "items": [{
      "task_id": "task_01JEXAMPLE",
      "status": "SUCCEEDED",
      "status_url": "/api/minimax/v1/tasks/task_01JEXAMPLE",
      "created_at": "2026-08-26T10:00:00Z",
      "progress": {
        "percent": 100,
        "stage": "SUCCEEDED",
        "generation_elapsed_seconds": 362,
        "updated_at": "2026-08-26T10:06:30Z"
      },
      "quota": {
        "quota_type": "AI_VIDEO_UNIT",
        "total_units": 480
      }
    }],
    "total": 1,
    "page": 1,
    "page_size": 20
  },
  "trace_id": "trace_01JEXAMPLE"
}

7. 查询积分余额

请求地址

GET /api/minimax/v1/quota/summary

请求头

参数	类型	是否必填	说明
`Authorization`	String	是	`Bearer <YOUR_API_KEY>`。

请求参数

本接口不需要 Query 参数和请求 Body。

请求示例

GET /api/minimax/v1/quota/summary
Authorization: Bearer <YOUR_API_KEY>

响应参数

参数	类型	说明
`total_points`	Integer	当前可用积分与预占积分之和。
`reserved_points`	Integer	已为排队或执行中任务预占的积分。
`available_points`	Integer	当前仍可用于创建任务的积分。

响应示例

{
  "code": "OK",
  "message": "OK",
  "data": {
    "total_points": 5000,
    "reserved_points": 480,
    "available_points": 4520
  },
  "trace_id": "trace_quota_summary"
}

total_points：当前可用积分与预占积分之和。
reserved_points：已为排队或执行中任务预占的积分。
available_points：当前仍可用于创建任务的积分。

账号尚未形成积分账户时返回三个零值。

8. 取消任务

请求地址

POST /api/minimax/v1/tasks/{taskId}/cancel

请求头

参数	类型	是否必填	说明
`Authorization`	String	是	`Bearer <YOUR_API_KEY>`。

路径参数

参数	类型	是否必填	说明
`taskId`	String	是	待取消任务的唯一标识。

请求参数

本接口不需要 Query 参数，请求 Body 必须为空。

请求示例

POST /api/minimax/v1/tasks/task_01JEXAMPLE/cancel
Authorization: Bearer <YOUR_API_KEY>
Content-Length: 0

响应参数

参数	类型	说明
`task_id`	String	任务唯一标识。
`status`	String	取消成功后为 `CANCELLED`。
`generations`	Array	被取消的生成记录列表。
`quota`	Object	本次任务的积分信息。
`trace_id`	String	请求追踪标识。

响应示例

{
  "code": "OK",
  "message": "OK",
  "data": {
    "task_id": "task_01JEXAMPLE",
    "status": "CANCELLED",
    "generations": [],
    "quota": {
      "quota_type": "AI_VIDEO_UNIT",
      "total_units": 480
    }
  },
  "trace_id": "trace_cancel_01JEXAMPLE"
}

请求必须发送零字节 Body，不要发送 {}。只有任务仍为 QUEUED 时允许取消；已经开始运行或进入终态时返回 HTTP 409、CANCEL_NOT_ALLOWED。取消成功后释放对应积分预占。

9. 常见错误

失败响应至少包含 code、message 和 trace_id；额度不足时额外返回 quota_type。调用方应依据稳定的 code 处理异常分支。

{
  "code": "INSUFFICIENT_QUOTA",
  "message": "积分不足，请购买或升级积分套餐后重试",
  "quota_type": "AI_VIDEO_UNIT",
  "trace_id": "trace_xxx"
}

HTTP	code	处理建议
400	`INVALID_PARAMETER`	检查字段类型、枚举、Header、时长和分页参数。
400	`INVALID_CONTENT`	检查文本、素材数量和音频组合。
400	`INVALID_MEDIA_URL`	检查素材 URL 是否为符合要求的 HTTPS 地址。
400	`INVALID_PROMPT_REFERENCE`	检查 `图N`、`视频N`、`音频N` 是否引用了实际提交的对应素材。
400	`REFERENCE_ASSET_REQUIRED`	`content` 未提供至少一个参考媒体。
400	`UNSUPPORTED_PARAMETER`	请求包含当前接口不支持的字段。
401	`INVALID_API_KEY`	检查 Bearer API Key 是否完整、有效且未删除。
404	`TASK_NOT_FOUND`	检查 task ID 是否属于当前 API Key。
409	`INSUFFICIENT_QUOTA`	`quota_type=AI_VIDEO_UNIT` 时积分不足，请购买或升级积分套餐后重试。
409	`CANCEL_NOT_ALLOWED`	任务已经开始或结束，不能取消。
413	`REMOTE_MEDIA_TOO_LARGE`	检查图片、视频或音频是否超过对应的单文件大小限制。
422	`INVALID_REMOTE_MEDIA`	检查远程素材是否为空、损坏或无法识别。
422	`REMOTE_MEDIA_TYPE_MISMATCH`	检查素材声明的类型是否与实际文件格式一致。
424	`REMOTE_MEDIA_DOWNLOAD_FAILED`	检查素材地址是否可访问，以及下载是否超时或被重定向策略拒绝。
429	`QUEUE_FULL`	稍后使用原 `Idempotency-Key` 重试。
503	`NO_CAPACITY`	当前没有可用生成资源，稍后使用原 `Idempotency-Key` 重试。
503	`TASK_CREATION_STATUS_UNKNOWN`	使用原 `Idempotency-Key` 重试确认。

反馈问题时可提供 trace_id、task_id 和 Idempotency-Key，不要提供完整 API Key 或素材私密地址。