Kelola Tugas Batch

Kirim permintaan massal asinkron dan periksa status eksekusi batch.

Kirim permintaan massal asinkron di berbagai titik akhir model yang didukung menggunakan Batch API yang kompatibel dengan OpenAI.

POST/openai/v1/batches

Badan Permintaan

BidangTipeWajibDeskripsi
input_file_idstringYaPengenal unik file yang diunggah dengan tujuan diatur ke batch.
endpointstringYaTitik akhir target (/v1/chat/completions, /v1/completions, /v1/responses, atau /v1/embeddings).
completion_windowstringYaBatas waktu penyelesaian, saat ini ditetapkan pada 24h.
metadataobjectTidakPasangan kunci-nilai opsional untuk pelacakan dan audit.

File input harus berupa UTF-8 JSONL dengan maksimal 50.000 item dan batas ukuran file 200 MiB. Setiap baris JSONL harus berupa objek JSON yang valid dengan custom_id unik tidak kosong, method: "POST", url yang cocok dengan endpoint batch, dan objek body (dengan bidang model wajib untuk batch prabayar ketat). Untuk batch prabayar native, gateway memvalidasi checksum file dan kebijakan eksekusi sebelum pendanaan; seluruh reservasi item dikomit secara atomik sebelum pengiriman ke penyedia. Dana agregat yang tidak mencukupi mengembalikan HTTP 402 tanpa pengiriman parsial. Konfigurasi penyedia yang tidak kompatibel tidak dapat dibagi dalam satu batch, dan failover lintas-penyedia tingkat item tidak dilakukan.

Siklus Hidup Batch

GET/openai/v1/batches/{batch_id}
POST/openai/v1/batches/{batch_id}/cancel
  • validating: Memverifikasi format file input, sintaksis JSONL, dan kepatuhan skema.
  • in_progress: Mendistribusikan item ke kredensial penyedia yang ditetapkan tanpa perpindahan antar-penyedia.
  • finalizing: Mengagregasikan hasil inferensi dan mencatat penyelesaian tagihan penggunaan.
  • completed: Pemrosesan selesai dengan sukses, menghasilkan output_file_id serta error_file_id opsional.
  • failed: Kegagalan terminal jika validasi file atau koordinasi batch gagal total.
  • cancelling: Menghentikan pemrosesan atas permintaan dan beralih ke status dibatalkan.
  • cancelled: Menandai eksekusi batch dihentikan sebelum penyelesaian akhir. Hasil item yang gagal, dibatalkan, atau hilang tidak membuktikan biaya penyedia nol; penyelesaian mempertahankan dana reservasi untuk rekonsiliasi terhadap catatan penyedia. Status kanonis di AnyInt adalah cancelled.
  • expired: Terpicu saat pemrosesan melebihi batas waktu 24 jam; eksekusi yang belum dikonfirmasi memerlukan rekonsiliasi berdasarkan catatan penyedia dan tidak berarti biaya nol dari hulu.

Daftar Batch dan Unduhan Hasil

GET/openai/v1/batches
  • Daftar batch: GET /openai/v1/batches mencantumkan tugas batch aktif dan historis untuk organisasi atau proyek yang diotorisasi.
  • Penyimpanan objek & unduhan: Penerimaan file dengan purpose: "batch" dan menjalankan operasi batch memerlukan penyimpanan objek bersama (OBJECT_STORE_MODE). Setelah selesai, file JSONL hasil dan kesalahan dapat diunduh melalui API file di GET /openai/v1/files/{file_id}/content.

Alias Kompatibilitas

  • Gateway menerima /v1/batches untuk kompatibilitas ke belakang; gunakan /openai/v1/batches untuk integrasi baru.