异步任务查询

​

图片任务查询接口

GET /v1/tasks/{task_id}

1. 图片异步模型
2. 其他走统一任务中心的异步能力

1. 响应体 code：成功查询时为数字 200。
2. data.task_id：提交接口返回的公开任务 ID。
3. data.status：submitted、processing、succeeded 或 failed。
4. data.works[]：有序图片作品数组。
5. data.works[].asset_url：平台稳定化后的图片地址。
6. data.fail_reason：仅任务失败时返回的公开失败原因。

{
  "code": 200,
  "data": {
    "task_id": "task_01KQEXAMPLE_IMAGE",
    "status": "succeeded",
    "works": [
      {
        "asset_url": "https://example.com/tasks/task_01KQEXAMPLE_IMAGE/result-01.png"
      },
      {
        "asset_url": "https://example.com/tasks/task_01KQEXAMPLE_IMAGE/result-02.png"
      }
    ]
  }
}

{
  "code": 200,
  "data": {
    "task_id": "task_01KQEXAMPLE_IMAGE",
    "status": "processing",
    "works": []
  }
}

{
  "code": 200,
  "data": {
    "task_id": "task_01KQEXAMPLE_IMAGE_FAILED",
    "status": "failed",
    "works": [],
    "fail_reason": "请求处理失败，请稍后重试"
  }
}

1. works 始终是数组，一张图片也返回一个元素的数组；协议允许一次任务返回多个作品。
2. images 是提交请求中的参考图数组，works 是任务查询中的输出作品数组。
3. asset_url 始终表示平台可直接使用的稳定结果地址，不暴露上游临时 URL。
4. 查询到失败任务仍属于查询成功，HTTP 状态码和响应体 code 都是 200；通过 data.status=failed 判断任务终态。
5. 鉴权失败、请求参数错误、任务不存在或服务异常使用对应 HTTP 状态码。
6. 文档站只描述图片正式对外字段；旧版图片响应中暂时保留的 result_url、progress 或内部任务字段不属于图片主协议。视频的 result_url 则是完成结果的正式主字段，不能与图片规则混用。

​

视频任务查询接口

GET /v1/videos/{task_id}

1. id：提交响应返回的公开视频任务 ID，查询路径中的 {task_id} 使用该值。
2. object：固定为 video。
3. model：本次任务使用的逻辑模型名称。
4. status：只允许 queued、in_progress、completed 或 failed。
5. progress：整数进度，通常为 0 到 100。
6. result_url：任务完成后的结果视频地址。
7. metadata.url：实现提供的补充结果地址，与 result_url 相同；接入方应优先读取顶层 result_url。
8. error：失败任务的结构化错误信息。
9. fail_reason：失败任务的公开失败原因。

{
  "id": "task_01KQEXAMPLE_VIDEO",
  "object": "video",
  "model": "sora-2",
  "status": "completed",
  "progress": 100,
  "result_url": "https://example.com/tasks/task_01KQEXAMPLE_VIDEO/result.mp4",
  "metadata": {
    "url": "https://example.com/tasks/task_01KQEXAMPLE_VIDEO/result.mp4"
  }
}

{
  "id": "task_01KQEXAMPLE_VIDEO_FAILED",
  "object": "video",
  "model": "sora-2",
  "status": "failed",
  "progress": 100,
  "error": {
    "code": "task_failed",
    "message": "请求处理失败，请稍后重试"
  },
  "fail_reason": "请求处理失败，请稍后重试"
}

1. gemini-omni-flash 的 default / standard 两组都统一走 GET /v1/videos/{task_id} 查询结果。
2. 当前所有视频逻辑模型统一使用同一个查询接口，不需要按模型实现差异区分轮询地址。
3. 视频任务处于 queued 或 in_progress 时继续轮询；不要使用图片任务的 processing 状态判断视频进度。
4. 视频任务查询成功时，统一从顶层 result_url 读取结果地址；metadata.url 是同一地址的补充字段。
5. 失败任务使用顶层 error 和 fail_reason 说明原因；失败状态仍是合法的任务查询结果。

​

典型流程

1. 调用生成接口
2. 获取任务 ID
3. 根据模型类型选择对应查询接口
4. 图片任务成功后遍历 data.works[]；视频任务成功后读取顶层 result_url

​

常见状态

​

图片任务

1. submitted
2. processing
3. succeeded
4. failed

​

视频任务

1. queued
2. in_progress
3. completed
4. failed

​

轮询建议

1. 首次查询建议在提交后数秒开始。
2. 轮询间隔建议控制在 2 到 5 秒。
3. 任务结束后停止轮询，避免无效请求。