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