Skip to main content
OpenAI Tasks API 用於查詢此前以 回調模式 提交到 OpenAI 圖片接口的任務結果。當您無法等待同步 HTTP 回應、或希望事後再次查詢任務時,請使用本接口。 回調模式下,原始的圖片接口在受理請求後會立即返回一個 task_id,您直接持有這個 task_id、並在需要時拿它到本接口查詢即可,無需額外傳遞自定義 trace_id(僅當您希望用自有業務標識做關聯時才需要)。
僅當原始圖片請求中帶有 callback_url 時,任務才會被持久化。同步(非回調)方式調用的請求不會被存儲。

申請流程

OpenAI Tasks API 與現有 OpenAI 服務共用授權。如果您已經申請了 OpenAI Images Generations,可直接使用相同的 token 調用本接口,無需額外申請。 新用戶首次申請均有免費額度。

接口地址

支持的 action:

請求頭

  • accept: application/json
  • authorization: Bearer {token}
  • content-type: application/json

單任務查詢(retrieve)

請求體

id 和 trace_id 至少傳一個。一般情況下直接使用提交回應中的 id 即可,trace_id 僅在您希望用自定義業務標識做關聯時再傳。

代碼示例

CURL

Python

返回示例

任務存在時:
未匹配到任何任務時返回空對象:

欄位說明

  • id:原始圖片請求受理時生成的任務 ID。
  • trace_id:原始請求中傳入的自定義追蹤標識,便於客戶端業務做關聯。
  • type:任務類型。gpt-image 系列(如 gpt-image-2)寫入的任務為 images;gpt-image-1、nano-banana 等使用 images_generations / images_edits,部分聊天接口為 chat_completions_image。
  • request:原始請求的完整請求體。
  • response:回調完成時返回的最終回應體。
  • created_at / started_at / finished_at:Unix 時間戳(秒,浮點)。
  • elapsed:執行耗時(秒,浮點)。
  • application_id / user_id / credential_id:所屬應用、終端用戶、憑據 ID。

批量查詢(retrieve_batch)

請求體

ids / trace_ids / application_id / user_id 或 created_at_* 時間窗口擇一傳入即可。

CURL 示例

返回示例

端到端示例:提交並輪詢

Tasks API 主要服務於回調模式下的異步流程。回調模式下,提交接口會立即同步返回一個 task_id(即任務 ID),之後您只需直接拿這個 task_id 去 Tasks 接口輪詢即可,無需自己再生成 trace_id。

注意事項

  • Tasks 接口本身不計費,可以放心輪詢。僅原始的圖片生成/編輯請求會扣費。
  • 僅當原始請求包含 callback_url 時,才會寫入任務記錄;同步調用不會產生可查詢的任務。
  • 超過平台保留期的任務記錄可能被清理。