任务查询 GET /v1/tasks/{task_no}

轮询异步任务状态与结果。task_no 为 视频生成 POST /v1/videos/generations 响应里的 id 字段。

端点

GET https://api.imodel.space/v1/tasks/{task_no}
Authorization: Bearer YOUR_API_KEY

路径参数

字段	类型	必传	说明
task_no	string	✅	任务编号，POST 创建任务时响应的 id 字段

响应字段

字段	类型	时机	说明
id	string	始终	任务编号
status	string	始终	任务状态（见下方枚举）
progress	integer	status = running	进度百分比（0-100）
created_at	integer	始终	任务创建时间（Unix 秒）
outputs	object[]	status = succeeded	视频产物 URL 列表（已走 gapi 代理，不暴露上游 ComfyUI 地址）
error	object { code, message }	status = failed	错误信息

状态枚举 status

值	说明
queued	已入队，等待调度（有空闲实例，排队等派发；或实例忙，等其释放）
scaling	初始化实例中中：系统正在为该任务创建新的 GPU 实例（拉取镜像约 1~3 分钟），完成后自动回到 queued 并派发
running	生成中，可读 progress 字段
succeeded	成功，outputs 是视频 URL 列表
failed	失败，error 字段含 code / message
cancelled	已取消（用户主动或上游超时）
timeout	排队超时（默认 15 分钟未获得实例），费用自动解冻
violation	违规（管理员在 admin 后台标记，产物文件已删除；该任务不可再访问产物，前端展示「任务涉及违规,不可展示」）

轮询提示：queued 与 scaling 都属于「排队等待」范畴，客户端轮询逻辑无需区分 —— 两者都未到终态，继续按既有间隔轮询即可。scaling 是 2026-09-05 新增的中间展示态，旧客户端将其按非终态处理即可自然兼容。

成功响应示例

HTTP 200

{
  "id": "v_7f9c1d3a-1b2c-4d5e-8a9f-0c1d2e3f4a5b",
  "status": "succeeded",
  "progress": 100,
  "created_at": 1763692800,
  "outputs": [
    {
      "url": "/api/asset/video/v_7f9c1d3a-1b2c-4d5e-8a9f-0c1d2e3f4a5b",
      "duration": 6,
      "resolution": "768P"
    }
  ]
}

status = scaling 时响应示例（实例初始化中，无 progress 字段）：

{
  "id": "v_7f9c1d3a-...",
  "status": "scaling",
  "created_at": 1763692800
}

失败响应示例

HTTP 200（注意：失败时本端点仍返回 200，错误信息放在响应体 error 字段里）

{
  "id": "v_xxx",
  "status": "failed",
  "created_at": 1763692800,
  "error": {
    "code": "minimax_h3_resolution_invalid",
    "message": "resolution must be one of [480P, 768P, 1080P, 1440P], got '720p'"
  }
}

轮询策略

场景	建议间隔
视频生成（4-15s 视频）	5s
running 状态卡住判断	30s 内 `prog初始化实例中 无变化视为卡死

取消任务

DELETE https://api.imodel.space/v1/tasks/{task_no}
```初始化实例中

返回 204 即视为取消成功；已经在执行的不会回滚，仅不再继续调度。

**可取消的状态**:`queued` / `scaling`(实例初始化中)/ `running` 之前尚未提交上游的排队任务。`running` 及终态(`succeeded` / `failed` / `cancelled` / `timeout`)返回 400。取消成功后已冻结的费用自动退还。

## 违规任务 `status = violation`

`violation` 是**终态**,仅由 admin 后台手工触发,**外部 API 不可触发**(没有公共 endpoint,只有 admin 角色可调用)。触发后:

- 任务对应产物文件从 COS 删除(若 `cos_key` 为空则跳过,幂等)
- `status` 改为 `violation`,`error.code = admin_marked_violation`
- `outputs` 字段会变为空(产物已删,前端不展示)
- 客户端轮询拿到该状态后,**应停止重试/重生成**,仅展示提示文案即可

**用户侧(前端 omni-generate)** 已经在状态徽章、卡片蒙层、详情页提示上做完整处理,你不需要再在前端做额外兜底。

## 文档更新记录

| 日期 | 更新内容 |
| --- | --- |
| 2026-09-06 | 状态枚举新增 `violation`(违规,admin 后台标记);新增「违规任务」小节说明终态语义与客户端处理 |
| 2026-09-05 | 状态枚举新增 `scaling`(实例初始化中)与 `timeout`(排队超时);补充 `queued` 的两种场景说明;取消任务一节明确可取消状态与费用退还;补轮询兼容性提示 |
| 2026-09-05 | 任务详情端点补充 `scaling` 状态的实际响应示例(此前详情端点在该阶段误返回 `queued`,已修复) |