Skip to main content
GET
  • 查询异步图片生成任务的执行状态和结果
  • 实时状态更新和进度跟踪
  • 任务完成时获取生成的图片
  • 支持多语言返回(zh/en/ko/ja)
所有图片生成任务都是异步执行的。提交任务后,您需要通过查询接口获取任务状态和结果。

创建任务时传入业务 ID

创建图片任务时,可以在请求体顶层传入 client_business_id。该字段用于保存您系统内的订单号、流水号或业务任务 ID,方便后续按业务 ID 查询生成结果。
也兼容放在 metadata.client_business_id 中,但推荐使用顶层字段。

Authorizations

string
必填
所有接口均需要使用 Bearer Token 进行认证获取 API Key:访问 API Key 管理页面 获取您的 API Key使用时在请求头中添加:

Path Parameters

string
必填
图片生成 API 返回的任务 ID。也可以传创建任务时提交的 client_business_id,用于按客户侧业务 ID 查询任务状态和结果。
如果创建图片任务时传入 client_business_id,可直接使用同一个状态查询接口: GET /v1/images/generations/{client_business_id}。业务 ID 会限定在当前 API Key 所属用户下查询。

Response

string
任务唯一标识符
string
客户侧业务 ID。仅当创建任务时传入 client_business_id 时返回。
string
对象类型,固定为 generation.task
string
使用的图片生成模型
string
任务状态
  • queued - 排队等待处理
  • in_progress - 处理中
  • completed - 成功完成
  • failed - 失败
integer
任务进度百分比(0-100)
integer
任务创建时间(Unix 时间戳)
integer
任务完成时间(Unix 时间戳,仅完成时返回)
integer
图片 URL 过期时间(Unix 时间戳,仅完成时返回)
object
任务结果(仅成功时返回)
object
错误信息(仅失败时返回)

任务状态说明

轮询策略建议

Python 轮询示例

图片资源有效期

生成的图片 URL 有效期为 24 小时
  • 请在有效期内下载保存图片
  • expires_at 字段标识图片过期时间(Unix 时间戳)
  • 图片过期后无法访问,如需重新获取,需要重新提交生成任务

常见错误

ToAPIs 支持统一 任务 Webhook。推荐回调为主、轮询兜底;至少间隔 5~10 秒并加入抖动,429 时读取 Retry-After。批量查询最多 100 个任务,详见 限流