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 個任務,詳見 限流。