管理批次任務

提交非同步批次請求並查詢批次執行狀態。

透過與 OpenAI 相容的 Batch API 跨支援的模型端點提交非同步批次處理請求。

POST/openai/v1/batches

請求體

欄位類型必填說明
input_file_idstring是用途設為 batch 的已上傳檔案唯一識別碼。
endpointstring是目標呼叫介面(/v1/chat/completions、/v1/completions、/v1/responses 或 /v1/embeddings)。
completion_windowstring是任務完成時間範圍,目前固定為 24h。
metadataobject否用於追蹤與檢索的選填鍵值組詮釋資料。

輸入檔案必須為 UTF-8 編碼的 JSONL 格式,單一檔案最多 50,000 筆項目,檔案大小上限為 200 MiB。每行必須為合法的 JSON 物件,包含唯一的非空 custom_id、值為 POST 的 method、與批次 endpoint 一致的 url,以及物件類型的 body(針對嚴格的原生預付費批次處理,body 中必須包含 model 欄位)。針對原生預付費批次處理,閘道在資金准入前對儲存檔案校驗和及各項目執行策略進行校驗;各項目預扣額度在供應商派發前原子化提交。整體資金不足時回傳 HTTP 402 且不執行部分派發。同一個批次內無法拆分不相容的供應商設定,且不執行項目級跨供應商容錯移轉。

批次生命週期

GET/openai/v1/batches/{batch_id}
POST/openai/v1/batches/{batch_id}/cancel
  • validating:驗證輸入檔案格式、JSONL 語法及項目結構規範。
  • in_progress:正在使用綁定的供應商憑證執行批次推論任務,不發生跨渠道偏移。
  • finalizing:彙整各項目推論產物並記錄用量與帳務結算憑證。
  • completed:批次完成,生成 output_file_id 以及選填的 error_file_id。
  • failed:輸入檔案校驗或批次調度全局失敗時記錄的終止異常狀態。
  • cancelling:收到取消請求,正在平順終止處理並流轉狀態。
  • cancelled:批次處理在全部完成前被主動終止。失敗、取消或缺失的結果項不自動代表零上游成本;帳務結算將保留預扣資金以待與供應商帳單核對。AnyInt 中的規範狀態標識為 cancelled。
  • expired:處理時間超出 24 小時完成窗口;未確認或執行中的項目需依據供應商記錄進行對帳,不自動代表零上游成本。

批次操作與產物下載

GET/openai/v1/batches
  • 列出批次:透過 GET /openai/v1/batches 查詢目前授權組織或專案下的歷史與活躍批次任務。
  • 物件儲存與下載:接收 purpose: "batch" 的檔案上傳與執行批次任務依賴叢集共享物件儲存(OBJECT_STORE_MODE)。任務完成後,輸出結果與錯誤 JSONL 檔案可透過檔案端點 GET /openai/v1/files/{file_id}/content 取得。

相容路徑

  • 閘道相容接收 /v1/batches 路徑;建議新整合統一使用 /openai/v1/batches。