获取任务状态
- 查询异步任务的执行状态和结果
- 实时状态更新和进度跟踪
- 任务完成时获取生成结果
- 支持 10 种语言的错误文案返回（en/zh/ja/ko/ru/fr/de/id/pt/es）
认证
所有接口均使用 Bearer Token 进行认证。
缺失或无效时返回 401。
获取 API Key：访问控制台 创建。
请求时在请求头中添加：
Authorization: Bearer YOUR_OAIRoute_KEYAll endpoints authenticate with a Bearer token.
Returns 401 when missing or invalid.
Get an API key: open the console and create one.
Add it to the request header:
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 queries use two families of paths; query on the same family you submitted with and never cross them:
| Submit endpoint | Matching query endpoint |
|---|---|
POST /v1/videos | GET /v1/tasks/{task_id} |
POST /v1/video/generations | GET /v1/video/generations/{task_id} |
POST /v1/videos (alias) | 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 |
A task submitted on a native path is known only to that native query path; looking it up at /v1/tasks/{task_id} returns not found.
Synchronous endpoints (such as /doubao/api/v3/images/generations and /v1/images/generations) have no task; the result is in the response itself.
查询参数
失败任务中 error.message 的返回语言。只影响该字段；不传或传入不支持的值时，返回原始错误文案。
可选值：en 英语、zh 简体中文、ja 日语、ko 韩语、ru 俄语、fr 法语、de 德语、id 印度尼西亚语、pt 葡萄牙语、es 西班牙语。
The language for error.message on failed tasks. Affects only that field; when omitted or set to an unsupported value, the original message is returned.
Options: en English, zh Simplified Chinese, ja Japanese, ko Korean, ru Russian, fr French, de German, id Indonesian, pt Portuguese, es Spanish.
响应
成功返回 { code, data }，失败返回 { error }。result 仅在状态为 completed 时出现，error 仅在状态为 failed 时出现。
任务唯一标识符。
任务状态值。pending 排队等待处理、processing 处理中、completed 成功完成、failed 失败、cancelled 用户取消。
本次任务扣费金额。
本次任务扣费积分。
任务进度百分比，0 到 100。
任务结果，仅在状态为 completed 时返回。
生成的图像对象数组，属于图像生成任务。每个元素含 url（数组）与 expires_at。
生成的视频对象数组，属于视频生成任务。
任务创建时间戳。
任务完成时间戳，仅在完成时存在。
预计完成时间，单位秒。
实际完成时间，单位秒，仅在完成时存在。
错误详情，仅在状态为 failed 时存在。
错误代码。
错误消息，随 language 参数切换语言。
错误类型，用于程序分支判断。
Success returns { code, data }; failure returns { error }. result appears only when the status is completed, and error only when it's failed.
The unique task identifier.
The task status. pending queued, processing in progress, completed succeeded, failed failed, cancelled cancelled by the user.
The amount charged for this task.
The credits charged for this task.
Task progress as a percentage, 0 to 100.
The task result; returned only when the status is completed.
The array of generated image objects, for image generation tasks. Each element has url (an array) and expires_at.
The array of generated video objects, for video generation tasks.
Task creation timestamp.
Task completion timestamp; present only when completed.
Estimated completion time in seconds.
Actual completion time in seconds; present only when completed.
Error details; present only when the status is failed.
The error code.
The error message, in the language given by the language parameter.
The error type, for program branching.
响应示例
成功（图像任务）：
{
"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
}
}失败：
{
"error": {
"code": 400,
"message": "无效的任务ID",
"type": "invalid_request_error"
}
}Success (image task):
{
"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
}
}Failure:
{
"error": {
"code": 400,
"message": "Invalid task ID",
"type": "invalid_request_error"
}
}错误码
| HTTP | type | 说明 |
|---|---|---|
| 400 | invalid_request_error | 无效的任务 ID |
| 401 | authentication_error | 身份验证失败，请检查您的 API 密钥 |
| 402 | payment_required | 账户余额不足，请充值后再试 |
| 429 | rate_limit_error | 请求过于频繁，请稍后再试 |
轮询图像任务建议每 5 到 10 秒一次，视频按实际耗时而定。任务一旦进入 completed 或 failed，状态不再变化，可以停止轮询。
| HTTP | type | Notes |
|---|---|---|
| 400 | invalid_request_error | Invalid task ID |
| 401 | authentication_error | Authentication failed; check your API key |
| 402 | payment_required | Insufficient account balance; top up and retry |
| 429 | rate_limit_error | Too many requests; try again later |
Poll image tasks every 5 to 10 seconds; for video, base the interval on actual duration. Once a task reaches completed or failed, its status stops changing and you can stop polling.
For more status codes and retry guidance see Error codes and rate limits; for troubleshooting steps on common errors see the FAQ.
使用示例
查询单个任务
用提交接口返回的 task_id 直接查。status 为 pending 或 processing 时继续等，completed 时结果在 result 里。
脚本轮询直到完成
循环查询直到状态落定。加最大重试次数，避免任务卡住时无限等待。
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只取结果文件
任务完成且产物字段可能是图片或视频，按需要取对应数组。
curl -s --header "Authorization: Bearer $YOUR_OAIRoute_KEY" \
"https://api.oairoute.com/v1/tasks/$TASK" \
| jq -r '(.result.images // .result.videos // [])[].url'Query a single task
Query directly with the task_id returned by the submit endpoint. While status is pending or processing, keep waiting; when it's completed, the result is in result.
Poll in a loop until done
Query repeatedly until the status settles. Add a maximum retry count so a stuck task doesn't wait forever.
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
doneTake only the result files
Once the task completes, the artifact field may hold images or videos; pick the array you need.
curl -s --header "Authorization: Bearer $YOUR_OAIRoute_KEY" \
"https://api.oairoute.com/v1/tasks/$TASK" \
| jq -r '(.result.images // .result.videos // [])[].url'