本文介绍 MiniMax H3 任务查询 API 的对接与使用。该接口用于查询、批量列出或删除 MiniMax H3 视频生成 API 创建的异步任务。
申请流程
要使用 MiniMax H3 任务查询 API,首先到 Ace Data Cloud 控制台 获取您的 API Token,留作备用。

如果你尚未登录或注册,会自动跳转到登录页面邀请你注册和登录,完成后会自动返回当前页面。
一个 API Token 即可调用平台所有服务,无需为每个服务单独申请。 首次申请会赠送免费额度,可免费体验;额度不足时可在 控制台 充值通用余额。
📘 完整文档:MiniMax H3 任务查询 API →
查询任务时应使用创建该任务的同一个 Token。建议将 Token 保存为环境变量,不要写入源码或提交到版本库:
1 |
export ACEDATACLOUD_API_KEY="YOUR_API_KEY" |
接口概览
- Base URL:
https://api.acedata.cloud - Endpoint:
POST /minimax/tasks - 认证方式:HTTP Header 中携带
authorization: Bearer {token} -
请求头:
accept: application/jsoncontent-type: application/json
-
查询单个任务:
action=retrieve,传入id - 批量查询任务:
action=retrieve_batch,可按任务 ID、时间范围和分页条件筛选 - 删除任务:
action=delete,传入id - 计费说明:任务查询免费,不会产生重复计费
创建视频后必须保存 task_id。推荐每隔约 10 秒查询一次,直到任务进入终态。
请求参数
| 参数 | 类型 | 必填 | 适用动作 | 说明 |
|---|---|---|---|---|
action |
string | 否 | 全部 | retrieve、retrieve_batch 或 delete;默认 retrieve |
id |
string | 条件必填 | retrieve、delete |
单个任务 ID |
ids |
string[] | 否 | retrieve_batch |
只返回指定任务 ID;省略时按其他条件列出任务 |
limit |
integer | 否 | retrieve_batch |
本次最多返回的任务数量 |
offset |
integer | 否 | retrieve_batch |
从结果列表中跳过的任务数量,用于分页 |
created_at_min |
number | 否 | retrieve_batch |
创建时间下限,Unix 时间戳,单位为秒 |
created_at_max |
number | 否 | retrieve_batch |
创建时间上限,Unix 时间戳,单位为秒 |
三种动作的用途如下:
action |
用途 | 必要参数 | 响应结构 |
|---|---|---|---|
retrieve |
查询一个任务的状态和结果 | id |
{ "task": {...} } |
retrieve_batch |
按任务 ID、时间和分页条件批量查询 | 可选 ids、时间范围、offset、limit |
{ "items": [...], "total": number } |
delete |
根据任务当前状态取消或删除任务记录 | id |
{ "id": "...", "deleted": true } |
查询单个任务
1 |
curl -X POST 'https://api.acedata.cloud/minimax/tasks' \ |
下面是一次真实成功任务的响应:
1 |
{ |
任务状态
status |
含义 | 客户端处理 |
|---|---|---|
queued |
已进入队列,等待执行 | 继续轮询 |
running |
正在生成 | 继续轮询 |
succeeded |
生成成功 | 读取 task.content.url,停止轮询 |
failed |
生成失败 | 读取 task.error,停止轮询 |
cancelled |
任务已取消 | 停止轮询 |
succeeded、failed 和 cancelled 都是终态。不要在进入终态后继续轮询。
task 响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
id |
string | 任务 ID |
model |
string | 任务使用的模型,当前为 MiniMax-H3 |
status |
string | 当前任务状态 |
error.code |
string | 失败错误码,仅失败时返回 |
error.message |
string | 失败原因,仅失败时返回 |
created_at |
integer | 创建时间,Unix 时间戳,单位为秒 |
updated_at |
integer | 最近一次状态更新时间,Unix 时间戳,单位为秒 |
content.url |
string | 成功后的视频地址 |
resolution |
string | 输出分辨率,768P 或 2K |
duration |
integer | 输出视频时长,单位为秒 |
usage.total_seconds |
integer | 总计费用量,等于输入视频秒数与输出秒数之和 |
usage.input_seconds |
integer | 参考视频输入产生的计费用量 |
usage.output_seconds |
integer | 输出视频产生的计费用量 |
usage.input_image_count |
integer | 计费统计中的输入图片数量 |
ratio |
string | 实际输出宽高比;使用 adaptive 时以这里的结果为准 |
task_type |
string | 视频生成任务为 generation |
modality |
string | 视频任务为 video |
Python 轮询完整示例
以下代码从环境变量读取 Token,创建任务后每隔 10 秒查询一次:
1 |
import os |
生产环境应为轮询设置总超时,并对 429 和临时 5xx 使用指数退避。网络超时不等于生成失败,可以使用同一个 task_id 继续查询。
批量查询
指定多个任务 ID:
1 |
curl -X POST 'https://api.acedata.cloud/minimax/tasks' \ |
按时间范围分页列出任务:
1 |
{ |
批量响应中的 items 使用与单任务查询相同的 task 字段,total 是筛选条件匹配的任务总数:
1 |
{ |
任务查询窗口为最近 7 天。超过该窗口的 task_id 可能返回无效任务;业务系统应在创建任务时保存 ID,并在成功后及时持久化结果 URL。
取消或删除任务
1 |
curl -X POST 'https://api.acedata.cloud/minimax/tasks' \ |
动作取决于任务当前状态:
| 当前状态 | 行为 |
|---|---|
queued |
取消尚未开始的任务 |
succeeded |
删除任务记录 |
failed |
删除任务记录 |
running |
不允许删除或取消,返回错误 |
cancelled |
不允许重复操作,返回错误 |
删除成功示例:
1 |
{ |
删除任务记录不会撤销已经完成的计费,也不能保证已保存的视频副本同时被删除。
失败响应与排查
失败任务仍以 HTTP 200 返回 task 对象,并在 task.error 中给出原因:
1 |
{ |
接口本身返回 400 时应检查 action 与条件参数,401 表示 Token 无效,429 表示查询过于频繁,500 表示服务暂时不可用。生成失败的任务不计费;成功任务按最终 usage 记录用量。











