# 获取任务状态
> 查询异步任务的执行状态和结果
> 实时状态更新和进度跟踪
> 任务完成时获取生成结果
> 支持 10 种语言的错误文案返回（en/zh/ja/ko/ru/fr/de/id/pt/es）
`GET /v1/tasks/{task_id}`
## 认证
- `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 缺失或无效时返回 401。 获取 API Key：[访问控制台](https://api.oairoute.com/keys) 创建。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_OAIRoute_KEY ```
## 路径对照
任务查询分两套路径，**提交用哪套，查询就用哪套**，不能交叉：
| 提交接口 | 对应的查询接口 |
|---|---|
| `POST /v1/videos` | `GET /v1/tasks/{task_id}` |
| `POST /v1/video/generations` | `GET /v1/video/generations/{task_id}` |
| `POST /v1/videos`（别名） | `GET /v1/videos/{task_id}` |
| `POST /doubao/api/v3/contents/generations/tasks` | `GET /doubao/api/v3/contents/generations/tasks/{task_id}` |
| `POST /mj/submit/imagine` | `GET /mj/task/{id}/fetch` |
用原生路径提交的任务，只有原生查询路径认识这个 ID；拿它去查 `/v1/tasks/{task_id}` 会返回未找到。
同步接口（如 `/doubao/api/v3/images/generations`、`/v1/images/generations`）**没有任务**，结果直接在响应体里，不要再来查。
## 路径参数
- `task_id` (string / 必填) — 生成接口返回的任务 ID。
## 查询参数
- `language` (string / 可选) — 失败任务中 `error.message` 的返回语言。只影响该字段；不传或传入不支持的值时，返回原始错误文案。 可选值：`en` 英语、`zh` 简体中文、`ja` 日语、`ko` 韩语、`ru` 俄语、`fr` 法语、`de` 德语、`id` 印度尼西亚语、`pt` 葡萄牙语、`es` 西班牙语。
## 响应
成功返回 `{ code, data }`，失败返回 `{ error }`。`result` 仅在状态为 `completed` 时出现，`error` 仅在状态为 `failed` 时出现。
- `id` (string) — 任务唯一标识符。
- `status` (string) — 任务状态值。`pending` 排队等待处理、`processing` 处理中、`completed` 成功完成、`failed` 失败、`cancelled` 用户取消。
- `cost` (number) — 本次任务扣费金额。
- `credits_cost` (number) — 本次任务扣费积分。
- `progress` (integer) — 任务进度百分比，0 到 100。
- `result` (object) — 任务结果，仅在状态为 `completed` 时返回。
- `result.images` (array) — 生成的图像对象数组，属于图像生成任务。每个元素含 `url`（数组）与 `expires_at`。
- `result.videos` (array) — 生成的视频对象数组，属于视频生成任务。
- `created` (integer) — 任务创建时间戳。
- `completed` (integer) — 任务完成时间戳，仅在完成时存在。
- `estimated_time` (integer) — 预计完成时间，单位秒。
- `actual_time` (integer) — 实际完成时间，单位秒，仅在完成时存在。
- `error` (object) — 错误详情，仅在状态为 `failed` 时存在。
- `error.code` (integer) — 错误代码。
- `error.message` (string) — 错误消息，随 `language` 参数切换语言。
- `error.type` (string) — 错误类型，用于程序分支判断。
## 响应示例
成功（图像任务）：
```json
{
  "code": 200,
  "data": {
    "id": "task_01KA040M0HP1GJWBJYZMKX1XS1",
    "status": "completed",
    "cost": 0.15,
    "credits_cost": 1.5,
    "progress": 100,
    "result": {
      "images": [
        {
          "url": ["https://cdn.oairoute.com/f/image/image_task_01KA0413RT2GGNZJ9GWQ4PXF2F_0.png"],
          "expires_at": 1763174708
        }
      ],
      "videos": []
    },
    "created": 1763088289,
    "completed": 1763088308,
    "estimated_time": 60,
    "actual_time": 19
  }
}
```
失败：
```json
{
  "error": {
    "code": 400,
    "message": "无效的任务ID",
    "type": "invalid_request_error"
  }
}
```
## 错误码
| HTTP | type | 说明 |
|---|---|---|
| 400 | invalid_request_error | 无效的任务 ID |
| 401 | authentication_error | 身份验证失败，请检查您的 API 密钥 |
| 402 | payment_required | 账户余额不足，请充值后再试 |
| 429 | rate_limit_error | 请求过于频繁，请稍后再试 |
> **Note:** 
> 轮询图像任务建议每 5 到 10 秒一次，视频按实际耗时而定。任务一旦进入 `completed` 或 `failed`，状态不再变化，可以停止轮询。
更多状态码与重试建议见[错误码与限流](../../support/errors.html)，常见报错的排查步骤见[常见问题](../../support/faq.html)。
## 使用示例
### 查询单个任务
用提交接口返回的 `task_id` 直接查。`status` 为 `pending` 或 `processing` 时继续等，`completed` 时结果在 `result` 里。
### 脚本轮询直到完成
循环查询直到状态落定。加最大重试次数，避免任务卡住时无限等待。
```bash
TASK=task_01KA040M0HP1GJWBJYZMKX1XS1
for i in $(seq 1 60); do
  STATUS=$(curl -s --header "Authorization: Bearer $YOUR_OAIRoute_KEY" \
    "https://api.oairoute.com/v1/tasks/$TASK" | jq -r '.status')
  echo "[$i] $STATUS"
  case "$STATUS" in
    completed|failed) break ;;
  esac
  sleep 8
done
```
### 只取结果文件
任务完成且产物字段可能是图片或视频，按需要取对应数组。
```bash
curl -s --header "Authorization: Bearer $YOUR_OAIRoute_KEY" \
  "https://api.oairoute.com/v1/tasks/$TASK" \
  | jq -r '(.result.images // .result.videos // [])[].url'
```
**获取任务状态{Get task status}::cURL**
```
curl --request GET \
  --url 'https://api.oairoute.com/v1/tasks/task_01KA040M0HP1GJWBJYZMKX1XS1?language=zh' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY'
```
**获取任务状态{Get task status}::Python**
```
import requests
url = "https://api.oairoute.com/v1/tasks/task_01KA040M0HP1GJWBJYZMKX1XS1"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
params = {"language": "zh"}
res = requests.get(url, headers=headers, params=params)
print(res.json())
```
**获取任务状态{Get task status}::JavaScript**
```
const url = new URL(
  "https://api.oairoute.com/v1/tasks/task_01KA040M0HP1GJWBJYZMKX1XS1"
);
url.searchParams.set("language", "zh");
fetch(url, {
  method: "GET",
  headers: { Authorization: "Bearer YOUR_OAIRoute_KEY" },
})
  .then((r) => r.json())
  .then(console.log);
```
**200 获取任务状态{Get task status}**
```
{
  "code": 200,
  "data": {
    "id": "task_01KA040M0HP1GJWBJYZMKX1XS1",
    "status": "completed",
    "cost": 0.15,
    "credits_cost": 1.5,
    "progress": 100,
    "result": {
      "images": [
        {
          "url": ["https://cdn.oairoute.com/f/image/task_01KA0413_0.png"],
          "expires_at": 1763174708
        }
      ],
      "videos": []
    },
    "created": 1763088289,
    "completed": 1763088308,
    "estimated_time": 60,
    "actual_time": 19
  }
}
```
**处理中{Processing}::cURL**
```
curl --request GET \
  --url 'https://api.oairoute.com/v1/tasks/task_01KA040M0HP1GJWBJYZMKX1XS1' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY'
```
**处理中{Processing}::Python**
```
import requests
url = "https://api.oairoute.com/v1/tasks/task_01KA040M0HP1GJWBJYZMKX1XS1"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
res = requests.get(url, headers=headers)
print(res.json())
```
**处理中{Processing}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/tasks/task_01KA040M0HP1GJWBJYZMKX1XS1", {
  headers: { Authorization: "Bearer YOUR_OAIRoute_KEY" },
});
console.log(await res.json());
```
**200 处理中{Processing}**
```
{
  "code": 200,
  "data": {
    "id": "task_01KA040M0HP1GJWBJYZMKX1XS1",
    "status": "processing",
    "cost": 0,
    "credits_cost": 0,
    "progress": 45,
    "created": 1763088289,
    "estimated_time": 60
  }
}
```