# 异步任务响应结构
> 图像与视频任务共用同一套查询响应
> 任务本身查询成功，失败信息在响应体里
> 判断终态看 `status`，不要看 HTTP 状态码
`GET /v1/tasks/{task_id}`
## 响应字段
- `id` (string) — 任务唯一标识。与提交时返回的一致。
- `status` (string) — 任务状态。取值 `pending`、`processing`、`completed`、`failed`、`cancelled`。 只有 `completed`、`failed`、`cancelled` 是终态，其余状态都应继续轮询。
- `progress` (integer) — 进度百分比，0 到 100。仅供参考，不要用它判断完成。
- `cost` (number) — 本次任务扣费金额。
- `credits_cost` (number) — 本次任务扣费积分。
- `result` (object) — 结果容器，`completed` 时才出现。
- `result.images` (array) — 生成的图像数组，属于图像任务。每个元素含 `url`（数组）、`sizes`、`output_formats`、`expires_at`。
- `result.videos` (array) — 生成的视频数组，属于视频任务。每个元素含 `url`（数组）与 `expires_at`。
- `created` (integer) — 创建时间，Unix 秒。
- `completed` (integer) — 完成时间，Unix 秒，仅在任务结束后出现。
- `estimated_time` (integer) — 预计耗时，单位秒。
- `actual_time` (integer) — 实际耗时，单位秒，仅在任务结束后出现。
- `error` (object) — 失败详情，仅在 `failed` 时出现。
- `error.code` (string) — 错误代码。注意这里是字符串，与同步错误的数字 `code` 类型不同。
- `error.message` (string) — 错误描述。可通过查询参数 `language` 切换语言。
- `error.type` (string) — 错误类型，用于程序分支判断。
## 四种状态的响应形态
**排队中：**
```json
{
  "code": 200,
  "data": {
    "id": "task_01KA",
    "status": "pending",
    "progress": 0,
    "created": 1763088289
  }
}
```
**处理中：**
```json
{
  "code": 200,
  "data": {
    "id": "task_01KA",
    "status": "processing",
    "progress": 45,
    "created": 1763088289
  }
}
```
**成功（图像任务）：**
```json
{
  "code": 200,
  "data": {
    "id": "task_01KA",
    "status": "completed",
    "progress": 100,
    "cost": 0.045,
    "credits_cost": 0.45,
    "result": {
      "images": [
        {
          "url": ["https://cdn.oairoute.com/f/image/task_01KA_0.png"],
          "sizes": ["2048x1152"],
          "output_formats": ["png"],
          "expires_at": [1763174708]
        }
      ],
      "videos": []
    },
    "created": 1763088289,
    "completed": 1763088379,
    "estimated_time": 90,
    "actual_time": 88
  }
}
```
**成功（视频任务）：**
```json
{
  "code": 200,
  "data": {
    "id": "task_01KA",
    "status": "completed",
    "progress": 100,
    "cost": 0.9,
    "result": {
      "videos": [
        {
          "url": ["https://cdn.oairoute.com/f/video/task_01KA.mp4"],
          "expires_at": 1763174708
        }
      ]
    },
    "created": 1763088289,
    "completed": 1763088400
  }
}
```
**失败：**
```json
{
  "code": 200,
  "data": {
    "id": "task_01KA",
    "status": "failed",
    "progress": 100,
    "cost": 0,
    "error": {
      "code": "content_policy_violation",
      "message": "提示词触发内容审核",
      "type": "invalid_request_error"
    },
    "created": 1763088289,
    "completed": 1763088301
  }
}
```
> **Note:** 
> `url` 是数组而不是字符串，下游模型可能返回多张结果。取第 0 项即可。地址带 `expires_at` 过期时间，请及时转存。
## 判断终态
轮询代码必须同时检查 HTTP 状态码与响应体的 `status`。只看 HTTP 状态码会漏掉任务级失败 —— 这类失败的任务本身查询是成功的，HTTP 仍是 200。
轮询间隔建议 5 到 10 秒。图像任务通常 1 到 3 分钟，视频任务 1 到 10 分钟。客户端总超时建议设到 15 分钟。
## 常见任务错误码
| code | 含义 | 处理方式 |
|---|---|---|
| `invalid_request_error` | 参数不合法 | 检查字段名与取值，不要重试 |
| `authentication_error` | 认证失败 | 换 Key，不要重试 |
| `permission_error` | 余额不足或无权限 | 充值或换模型 |
| `not_found_error` | 任务不存在 | 任务保留约 3 天，超期查询会返回 404 |
| `content_policy_violation` | 内容审核未通过 | 改提示词，原样重试仍会失败 |
| `SensitiveContentDetected` | 素材或产物触发审核 | 换素材 |
| `InvalidParameter.TaskTypeMismatch` | 声明的任务类型与提示词不符 | 改 `omni_reference_task_type` 或改提示词 |
| `upstream_timeout` | 上游超时 | 可以重试 |
| `internal_error` | 服务端异常 | 可以重试 |
## 计费影响
| 错误类型 | 是否扣费 | 是否退款 |
|---|---|---|
| 参数错误 | 不建任务，不扣费 | 不涉及 |
| 内容审核未通过 | 建了任务、扣了费 | 自动全额退款 |
| 上游超时 | 扣了费 | 自动全额退款 |
| 成功但结果不满意 | 扣了费 | 不退款 |
退款由系统自动完成，不需要手动申请。在用量接口里能看到对应的冲正记录。
## 重试策略
按错误码分三类：
**不要重试**：参数错误、认证失败、权限不足、内容审核。这些重试多少次结果都一样。
**可以重试**：上游超时、服务端异常。用指数退避，最多两三次。
**先改再试**：任务类型不匹配。重试前要改 `omni_reference_task_type` 或提示词，否则一定同样失败。
## 与同步错误的区别
同步接口失败时返回 HTTP 4xx 或 5xx，响应体是 `{ error: { code, message, type } }`，`code` 是数字。
异步任务失败时，任务查询本身返回 HTTP 200，失败信息在 `data.status` 与 `data.error` 里，`error.code` 是字符串。
两种结构不能共用同一套解析逻辑。完整状态码与重试建议见[错误码与限流](../../support/errors.html)。常见报错的排查步骤见[常见问题](../../support/faq.html)。