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.statussettled, 且已保存的用量有效并与最终扣费一致时返回图片 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 时, 也可能同时省略 billingusage.
  • 成功 Webhook 的 data.usage 可包含相同的图片 token 字段,data.billing 也可能包含已确认费用。任一字段缺失时,可查询本接口作为兜底。详见价格与实际费用

任务状态说明

轮询策略建议

Python 轮询示例

图片资源有效期

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

常见错误

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