获取任务 | Yeehoo Developers

统一查询图片、视频等异步任务状态，是生产环境最推荐使用的任务查询接口。

这是当前最推荐的任务查询接口。

GET /v1/tasks/{task_id}

接口概览

项	说明
路由	`GET /v1/tasks/{task_id}`
鉴权	`Authorization: Bearer sk_yeehoo_xxx`
路径参数	`task_id`
返回	`200 OK` + 任务对象

为什么推荐优先用它

图片和视频都能统一查询
业务层更容易做统一状态机
更适合轮询和 webhook 结合

Authorizations

Authorization: Bearer sk_yeehoo_your_api_key

Path Parameters

参数	类型	必填	说明
`task_id`	`string`	是	创建任务后返回的任务 ID

Response

成功时通常返回任务详情对象。

{
  "task_id": "task_01jxyz...",
  "object": "task",
  "kind": "image",
  "model": "gpt-image-2",
  "status": "succeeded",
  "progress": 100,
  "created_at": 1784779200,
  "completed_at": 1784779260,
  "result": {
    "data": [
      { "url": "https://cdn.aibubu.cn/generated/image.png" }
    ]
  }
}

响应字段说明

字段	类型	说明
`task_id`	`string`	任务 ID
`kind`	`string`	任务类型，如 `image` 或 `video`
`model`	`string`	实际执行模型
`status`	`string`	当前状态，如 `queued`、`running`、`succeeded`、`failed`
`progress`	`integer`	任务进度
`created_at`	`integer`	创建时间戳
`completed_at`	`integer`	完成时间戳
`result`	`object`	成功时的结果对象
`error`	`object`	失败时的错误对象

终态包括 succeeded、failed、canceled 和 expired。completed_at 仅在完成后返回，运行中通常省略，不应依赖固定的 0。

成功结果

result.data 是成功任务的资源列表。每一项都包含平台转存后的 url；视频有可用封面时，额外返回 thumbnail_url。

{
  "kind": "video",
  "status": "succeeded",
  "result": {
    "data": [
      {
        "url": "https://cdn.aibubu.cn/generated/video.mp4",
        "thumbnail_url": "https://cdn.aibubu.cn/generated/cover.png"
      }
    ]
  }
}

对外 API 不返回上游原始响应、渠道信息、内部计费或用量字段。任务类型以顶层 kind 判断；url 始终存在，thumbnail_url 仅视频任务在有可用封面时返回。

如业务需要长期保存结果，请及时下载并自行归档；不要把平台输出 URL 的永久有效性作为业务承诺。

接入建议

如果已经收到了 webhook，关键链路里仍建议再查一次任务终态
轮询频率不要过高，建议做退避或固定间隔
把任务查询结果作为最终状态源会更稳