查询 MiniMax H3 任务

GET /v2/query/video_generation/{task_id}

统一查询 H3/H3-Max 视频生成、2K 升级、Context-IR 任务。使用任务所属用户的 Authorization: Bearer {apiKey}，无需请求体。

路径参数

参数	类型	必选	说明
`task_id`	string	是	创建接口返回的平台任务 ID；不是上游 ID

curl "{baseUrl}/v2/query/video_generation/{task_id}" \
  -H "Authorization: Bearer {apiKey}"

响应字段（HTTP 200）

字段	类型	说明
`task.id`	string	平台任务 ID，与提交返回的 task_id 一致
`task.model`	string	请求模型：MiniMax-H3 或 MiniMax-H3-Max
`task.status`	string	queued、running、succeeded、failed、cancelled
`task.task_type`	string	generation、regeneration、h3_context_ir
`task.modality`	string	视频为 video；Context-IR 为 text
`task.content.url`	string	视频生成／升级成功时的视频地址
`task.content.prompt`	string	Context-IR 成功时的提示词
`task.resolution`	string	可选，上游结果包含时返回
`task.duration`	integer	可选，上游结果包含时返回
`task.ratio`	string	可选，上游结果包含时返回
`task.created_at`	integer	创建时间戳（秒）；无上游值时使用平台提交时间
`task.updated_at`	integer	可选，上游结果包含时返回
`task.error`	object	失败信息，含 type、message 等字段

查询和客户回调不提供上游任务 ID、上游 usage。可选字段不保证存在；处理中可能没有 content，失败时平台移除 content。请先判断状态，再读取对应结果字段。

状态处理

状态	处理方式
`queued`	平台已建单／排队，继续查询；不保证已确认上游受理
`running`	处理中，继续查询
`succeeded`	成功；按 modality 读取 URL 或 prompt，停止轮询
`failed`	失败；检查 error，停止轮询
`cancelled`	上游取消；停止轮询。此状态不表示平台提供取消接口

平台刷新上游暂时失败时，查询可能仍以 HTTP 200 返回已有持久化状态。因此单次 queued/running 响应不代表上游刚刚确认了该状态。建议每 5–10 秒查询，并结合控制台任务日志排查长时间未变化的任务。

视频成功示例

{
  "task": {
    "id": "task_platform_example",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "task_type": "generation",
    "modality": "video",
    "resolution": "768P",
    "content": {"url": "https://example.com/generated-video.mp4"},
    "created_at": 1792540800
  }
}

结果 URL 请及时下载或转存；本接口不承诺固定的 URL 有效期。示例地址仅说明结构。

失败任务示例

{
  "task": {
    "id": "task_platform_example",
    "model": "MiniMax-H3",
    "status": "failed",
    "task_type": "generation",
    "modality": "video",
    "error": {"type": "platform_error", "message": "任务失败原因"},
    "created_at": 1792540800
  }
}

任务失败响应可为 HTTP 200，和请求本身失败的 HTTP 4xx/5xx 是两类情况。

错误处理

请求层错误示例（文案随语言与具体原因变化，http_code 是字符串）：

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "任务不存在或无权访问",
    "http_code": "404"
  },
  "request_id": "request_example"
}

HTTP 状态	常见原因与处理
400	模型／时长／分辨率／媒体组合无效、源任务不满足条件、回调校验失败；按 error.message 修正
401	模型密钥缺失或无效，检查 Authorization
403	令牌模型权限、分组或绑定渠道不满足要求
404	任务不存在、不属于当前用户、不是 H3 任务或不属于当前环境
413	请求体超过大小限制
5xx	平台或上游暂时异常；已有 task_id 时优先查询，避免重复创建

代理层也可能返回 HTML 等非 JSON 错误。如果 POST /v2/... 返回 HTML 405，请核对请求地址并联系管理员确认 /v2/ 已正确转发至后端。

路径参数​

响应字段（HTTP 200）​

状态处理​

视频成功示例​

失败任务示例​

错误处理​