异步任务响应结构

  • 图像与视频任务共用同一套查询响应
  • 任务本身查询成功，失败信息在响应体里
  • 判断终态看 status，不要看 HTTP 状态码
GET/v1/tasks/{task_id}

响应字段

string

任务唯一标识。与提交时返回的一致。

string

任务状态。取值 pending、processing、completed、failed、cancelled。

只有 completed、failed、cancelled 是终态，其余状态都应继续轮询。

integer

进度百分比，0 到 100。仅供参考，不要用它判断完成。

number

本次任务扣费金额。

number

本次任务扣费积分。

object

结果容器，completed 时才出现。

result 的元素字段 · 2 项
array

生成的图像数组，属于图像任务。每个元素含 url（数组）、sizes、output_formats、expires_at。

array

生成的视频数组，属于视频任务。每个元素含 url（数组）与 expires_at。

integer

创建时间，Unix 秒。

integer

完成时间，Unix 秒，仅在任务结束后出现。

integer

预计耗时，单位秒。

integer

实际耗时，单位秒，仅在任务结束后出现。

object

失败详情，仅在 failed 时出现。

error 的元素字段 · 3 项
string

错误代码。注意这里是字符串，与同步错误的数字 code 类型不同。

string

错误描述。可通过查询参数 language 切换语言。

string

错误类型，用于程序分支判断。

四种状态的响应形态

排队中：

{
  "code": 200,
  "data": {
    "id": "task_01KA",
    "status": "pending",
    "progress": 0,
    "created": 1763088289
  }
}

处理中：

{
  "code": 200,
  "data": {
    "id": "task_01KA",
    "status": "processing",
    "progress": 45,
    "created": 1763088289
  }
}

成功（图像任务）：

{
  "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
  }
}

成功（视频任务）：

{
  "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
  }
}

失败：

{
  "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
  }
}

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 是字符串。

两种结构不能共用同一套解析逻辑。完整状态码与重试建议见错误码与限流。常见报错的排查步骤见常见问题。