Skip to main content
GET
国内用户请注意: 中国大陆用户请使用 https://toapis.cn 作为接口地址(Base URL)。文档示例中的 https://toapis.com 请替换为 https://toapis.cn。
  • 查询异步图片生成任务的执行状态和结果
  • 实时状态更新和进度跟踪
  • 任务完成时获取生成的图片
  • 支持多语言返回(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
可选的图片任务计费信息. 计费状态独立于任务生成状态, completed 不保证已经结算. 无法确认计费数据时省略整个 billing, 不返回 null, 也不代表免费.
object
可选的已结算图片 token 用量. 仅在 billing.status 为 settled, 且已保存的用量有效并与最终扣费一致时返回图片 token 字段. 缺失或无法校验时省略, 不估算, 不用零值代替; 已确认的金额和图片结果仍可正常返回.所有 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 可包含相同的图片 token 字段,data.billing 也可能包含已确认费用。任一字段缺失时,可查询本接口作为兜底。详见价格与实际费用。

任务状态说明

轮询策略建议

Python 轮询示例

图片资源有效期

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

常见错误

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