Skip to main content
GET
国内用户请注意: 中国大陆用户请使用 https://toapis.cn 作为接口地址(Base URL)。文档示例中的 https://toapis.com 请替换为 https://toapis.cn。
  • 查询异步图片生成任务的执行状态和结果
  • 实时状态更新和进度跟踪
  • 任务完成时获取生成的图片
  • 支持多语言返回(zh/en/ko/ja)
所有图片生成任务都是异步执行的。提交任务后,您需要通过查询接口获取任务状态和结果。 普通图片和视频任务也可通过 GET /v1/tasks/{task_id} 查询, usage 和 billing 采用相同口径. 本页描述的是页首生成任务查询路径的响应. 以下样例用于展示字段, 不代表模型的当前价格或固定计费方式. 实际字段和金额以本次任务返回为准.

创建任务时传入业务 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
任务完成时间(Unix 时间戳,仅完成时返回)
integer
图片 URL 过期时间(Unix 时间戳,仅完成时返回)
object
任务结果(仅成功时返回)
object
可选的图片任务计费信息. 计费状态独立于任务生成状态, completed 不保证已经结算. 无法确认计费数据时省略整个 billing, 不返回 null, 也不代表免费.
object
可选的计费量, 图片 token 明细和工具次数. charge_type, requests, billed_tokens 等字段见任务用量字段. 图片 token 明细仅在 billing.status 为 settled, 且保存的用量有效并与最终扣费一致时返回. 无法确认的部分省略, 已确认的金额和图片结果仍可正常返回.charge_type, requests, billed_tokens 和 input_images 是计费量, 只与 billing.status=settled 同时返回. 提交时一次扣清的按次任务同样返回 settled 和实际金额. 所有 token 数均为非负 JSON 整数. 缓存 token 是输入 token 的子集, 不能重复相加. output_tokens_details 在未提供明细时整体省略. usage.tool_usage.web_search 可独立返回, 也可与图片 token 并存.
object
错误信息(仅失败时返回)

计费状态与消费统计

上述计费规则适用于图片任务查询, 不限制模型或渠道. GPT-Image-2.5 的 Sunburst 和 Flare VIP / Official 型号已接通 token 用量, 其他模型是否返回取决于已有结算数据. 示例金额仅用于说明响应格式, 不是固定单价.
  • 金额来自任务已确认的最终扣费, 查询不会触发扣款, 补扣或退款, 也不会按最新模型价格重算. 统计时直接使用返回金额, 不要用 token 乘当前单价替代.
  • 按任务 id 去重并更新金额, 不要累加每次轮询的返回值. 使用十进制计算; pending 或字段缺失不能按零消费处理.
  • 金额使用十进制字符串, 不保证固定小数位数.
  • 计费记录缺失或不一致时可能省略 billing. 图片尚不可交付而临时显示为 in_progress 时, 也可能同时省略 billing 和 usage.
  • 成功 Webhook 的 data.usage 和 data.billing 与本接口使用同一确认条件和字段取值. Webhook 是事件创建时的快照, 字段缺失时可查询本接口作为兜底. 详见价格与实际费用.

任务状态说明

轮询策略建议

Python 轮询示例

图片资源有效期

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

错误码与失败原因

请求错误和任务执行失败的区别, 具体错误标识与处理建议, 见错误码速查. 查询成功仍需检查任务状态, 不要把 HTTP 状态码当作业务错误码.
ToAPIs 支持统一 任务 Webhook。推荐回调为主、轮询兜底;至少间隔 5~10 秒并加入抖动,429 时读取 Retry-After。批量查询最多 100 个任务,详见 限流。