Cara Menggunakan OpenAI Batch API

Pada akhir panduan ini Anda akan dapat memanggil OpenAI Batch API untuk menjalankan ribuan permintaan model sebagai satu pekerjaan asinkron dan mendapatkan setiap hasil dengan diskon 50%. Anda akan mengemas prompt Anda ke dalam file JSONL, mengirimkan satu batch, melakukan polling sampai selesai, dan mengunduh hasilnya, kemudian menguji setiap langkah di Apidog sebelum mengintegrasikannya ke dalam produksi. Jika pekerjaan Anda lebih interaktif, jalur sinkron lebih cocok, dan Anda dapat menguji ChatGPT API dengan Apidog sebagai gantinya.

Apa itu Batch API dan Kapan Menggunakannya

Batch API adalah endpoint asinkron untuk volume panggilan model besar yang dapat mentolerir penundaan. Alih-alih satu permintaan HTTP per prompt, Anda mengemas banyak permintaan ke dalam satu file JSONL, mengirimkannya sebagai satu pekerjaan, dan melakukan polling untuk penyelesaian. OpenAI menjalankan pekerjaan pada jam non-puncak dan mengembalikan setiap hasil dalam file keluaran.

Anda mendapatkan dua manfaat nyata. Pertama, diskon tetap 50% untuk token input dan output dibandingkan dengan API sinkron. Kedua, throughput yang lebih tinggi, karena pekerjaan batch menggunakan kumpulan batas laju terpisah dan tidak bersaing dengan lalu lintas langsung Anda. Komprominya adalah latensi. OpenAI berkomitmen untuk menyelesaikan dalam waktu 24 jam; banyak pekerjaan selesai lebih cepat, tetapi Anda tidak bisa mengandalkannya.

Gunakan pemrosesan batch ketika pekerjaan bersifat offline dan berbentuk massal:

• Mengklasifikasikan atau memberi tag tumpukan catatan yang belum dikerjakan
• Menghasilkan embedding untuk seluruh korpus
• Pembuatan konten massal (deskripsi produk, ringkasan, terjemahan)
• Menjalankan suite evaluasi atau perbandingan model pada sebuah dataset

Lewati ini untuk apa pun yang sedang ditunggu pengguna. UI Obrolan, pelengkapan otomatis, dan agen langsung memerlukan endpoint sinkron. Jika Anda menghasilkan banyak konfigurasi model atau agen sekaligus, pemrosesan batch sangat cocok dengan beban kerja tersebut; lihat panduan kami tentang menghasilkan 100+ konfigurasi agen dengan pemrosesan batch.

Yang Anda Butuhkan Sebelum Memulai

Seluruh alur mencakup dua endpoint, /v1/files dan /v1/batches, serta empat langkah. Berikut adalah bentuknya sebelum kita melihat panggilannya.

Untuk mengikuti, Anda memerlukan kunci API OpenAI yang diekspor sebagai OPENAI_API_KEY, file JSONL berisi permintaan, dan alat untuk memicu serta memeriksa panggilan. Setiap langkah mengembalikan objek yang dapat Anda pastikan, yang membuat seluruh siklus hidup mudah diuji.

Langkah 1: Buat dan Unggah File JSONL

Input Anda adalah file JSONL di mana setiap baris adalah satu permintaan yang berdiri sendiri. Setiap baris memerlukan empat bidang: custom_id yang Anda pilih (sehingga Anda dapat mencocokkan hasil kembali ke input), method (POST), url (endpoint target seperti /v1/chat/completions), dan body yang berisi parameter permintaan sebenarnya.

{"custom_id": "req-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4.1-mini", "messages": [{"role": "user", "content": "Classify the sentiment of: 'shipping was slow but the product is great'"}]}}
{"custom_id": "req-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4.1-mini", "messages": [{"role": "user", "content": "Classify the sentiment of: 'returned it the same day'"}]}}

custom_id harus unik di dalam file. Hasil kembali tanpa urutan yang dijamin, jadi ID tersebut adalah cara Anda menghubungkan setiap respons ke baris sumbernya. Satu batch dapat menampung hingga 50.000 permintaan dan ukuran file dapat mencapai 200 MB.

Unggah ke Files API dengan purpose batch:

curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="batch" \
  -F file="@requests.jsonl"

Respons membawa id file (sesuatu seperti file-abc123). Itulah input_file_id Anda untuk langkah selanjutnya.

Langkah 2: Buat Batch

Sekarang buat pekerjaan. Anda meneruskan input_file_id, endpoint yang Anda targetkan, dan completion_window. Saat ini completion_window menerima satu nilai, "24h".

curl https://api.openai.com/v1/batches \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file-abc123",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h",
    "metadata": {"job": "sentiment-backfill"}
  }'

Bidang endpoint harus cocok dengan url yang digunakan di dalam baris JSONL Anda. Target yang didukung termasuk /v1/chat/completions, /v1/responses, /v1/embeddings, /v1/completions, dan /v1/moderations, di antara lainnya. Objek metadata opsional menampung hingga 16 pasangan kunci-nilai, yang berguna untuk memberi tag pekerjaan yang ingin Anda saring nanti.

Panggilan tersebut mengembalikan objek batch. Bidang-bidang yang paling akan Anda perhatikan:

{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "request_counts": { "total": 0, "completed": 0, "failed": 0 },
  "created_at": 1733452800,
  "metadata": { "job": "sentiment-backfill" }
}

Langkah 3: Polling Status Batch

Batch baru dimulai dengan status validating. Dari sana, batch bergerak melalui serangkaian status yang didokumentasikan. Lakukan polling GET /v1/batches/{batch_id} dan baca bidang status.

Objek request_counts (total, completed, failed) memberi Anda progres langsung saat status berada di in_progress. Tidak ada webhook yang perlu ditunggu di sini, jadi melakukan polling pada interval yang masuk akal (setiap beberapa menit, bukan setiap detik) adalah pola yang tepat. Anda juga dapat membatalkan pekerjaan yang sedang berjalan dengan POST /v1/batches/{batch_id}/cancel jika Anda tidak sengaja mengirimkannya.

Langkah 4: Ambil Output

Ketika status terbaca completed, objek batch membawa output_file_id. Unduh isi file tersebut melalui Files API:

curl https://api.openai.com/v1/files/file-output456/content \
  -H "Authorization: Bearer $OPENAI_API_KEY" > results.jsonl

Outputnya kembali dalam format JSONL, satu baris per permintaan. Setiap baris mengulang custom_id yang Anda atur, ditambah objek response yang berisi kode status dan body. Setiap permintaan yang mengalami error akan muncul dalam file yang dirujuk oleh error_file_id, jadi periksa keduanya. Cocokkan hasil dengan input berdasarkan custom_id, bukan berdasarkan urutan baris.

Perhatikan Kompromi Biaya dan Jendela Waktu

Perhitungannya sederhana: Anda menghemat 50% pada token dan Anda menerima waktu penyelesaian hingga 24 jam. Untuk pengisian data kembali satu kali atau pekerjaan malam, itu adalah pilihan yang mudah. Untuk fitur di jalur kritis produk Anda, itu tidak berlaku.

Beberapa catatan praktis:

• Diskon berlaku untuk token input dan output, di seluruh model yang didukung.
• Jendela 24 jam adalah batas atas, bukan target. Rencanakan untuk skenario terburuk; jika suatu pekerjaan mencapai status expired, permintaan yang selesai masih akan ditagih dan dikembalikan, dan sisanya tidak.
• Pekerjaan batch menggunakan batas token antrean terpisah, sehingga batch besar tidak akan mengganggu batas laju yang menjadi sandaran lalu lintas langsung Anda. Jika Anda sudah mencapai batas, panduan kami tentang batas laju GPT API dan cara mengujinya mencakup sisi sinkron.
• Token setengah harga masih bertambah dengan volume. Lacak pengeluaran per pekerjaan menggunakan tag metadata sehingga Anda dapat mengatribusikan biaya nanti; berikut adalah panduan atribusi biaya untuk pengeluaran OpenAI.

Cara Mengujinya di Apidog

Batch API lebih rentan kesalahan daripada satu panggilan chat, karena mode kegagalannya tersebar di seluruh file, format JSONL, dan loop polling. Baris yang salah format dalam file 50.000 permintaan akan menggagalkan seluruh unggahan, dan Anda tidak akan tahu sampai validasi berjalan. Menguji endpoint siklus hidup sebelum Anda mengotomatisasinya akan menghemat waktu Anda.

Apidog adalah platform API tempat Anda dapat menjalankan setiap langkah sebagai permintaan, merangkainya, dan menegaskan responsnya. Ini menguji dan memalsukan endpoint; ini bukan SDK OpenAI. Penyiapan yang realistis terlihat seperti ini:

• Validasi bentuk JSONL terlebih dahulu. Sebelum mengunggah apa pun, pastikan setiap baris membawa custom_id, method, url, dan body, serta body.model dan pesan-pesan ada. Menemukan bidang yang hilang secara lokal lebih murah daripada batch yang gagal.
• Jalankan unggahan multipart. Kirim POST /v1/files dengan purpose=batch dan file Anda, lalu tangkap id yang dikembalikan ke dalam variabel lingkungan.
• Buat batch dan pastikan objeknya. Lakukan POST /v1/batches, lalu pastikan bahwa status adalah validating dan endpoint cocok dengan yang Anda kirim. Penegasan visual Apidog memungkinkan Anda memeriksa bidang-bidang tersebut tanpa menulis skrip.
• Polling dan ambil. Lakukan GET /v1/batches/{id} dalam loop, pastikan ketika status menjadi completed, lalu tarik output_file_id dan unduh hasilnya.
• Latih jalur pembatalan dan kesalahan. Kirim file yang sengaja rusak dan pastikan Anda mendapatkan status failed, dan uji POST /v1/batches/{id}/cancel agar penanganan kesalahan Anda nyata, bukan asumsi.

Karena file output tiba nanti, Anda juga dapat menyiapkan API tiruan yang mengembalikan objek batch yang selesai dan file hasil siap pakai. Hal itu memungkinkan Anda membangun dan menguji logika pengambilan dan penguraian Anda tanpa menunggu pekerjaan nyata 24 jam, dan tanpa membakar token selama pengembangan. Ketika tim Anda bekerja berdasarkan spesifikasi terlebih dahulu, Anda juga dapat menghasilkan koleksi pengujian langsung dari spesifikasi OpenAPI dan menjaga endpoint batch di bawah cakupan regresi di CI.

Pertanyaan yang Sering Diajukan

Berapa Lama Waktu yang Dibutuhkan untuk Sebuah Batch?

OpenAI berkomitmen untuk menyelesaikan batch dalam waktu 24 jam. Pada praktiknya, banyak pekerjaan selesai lebih cepat, tetapi jaminannya adalah batas waktu 24 jam, jadi bangun sistem Anda berdasarkan itu. Jika jendela waktu ditutup dengan pekerjaan yang belum selesai, batch berpindah ke status expired dan hanya permintaan yang selesai yang dikembalikan dan ditagih.

Berapa Diskon Sebenarnya, dan Apakah Bisa Ditumpuk?

Batch API memberikan diskon tetap 50% dibandingkan endpoint sinkron, baik untuk token input maupun output. Ini adalah pengungkit biaya terbesar yang ditawarkan OpenAI untuk beban kerja offline. Jika Anda mencoba mengatribusikan pengeluaran tersebut kembali ke fitur atau pekerjaan, panduan atribusi biaya menunjukkan cara membaginya.

Endpoint Mana yang Dapat Saya Jalankan dalam Sebuah Batch?

Anda mengatur target baik di bidang url JSONL maupun endpoint batch, dan keduanya harus cocok. Target yang didukung termasuk /v1/chat/completions, /v1/responses, /v1/embeddings, /v1/completions, dan /v1/moderations, ditambah endpoint gambar dan video. Periksa dokumentasi terbaru untuk daftar lengkapnya, karena OpenAI menambahkannya seiring waktu.

Mengapa Hasil Saya Tidak Berurutan?

Mereka tidak berurutan, berdasarkan desain. JSONL output tidak mempertahankan urutan baris input, itulah sebabnya setiap permintaan memerlukan custom_id yang unik. Cocokkan hasil dengan input berdasarkan ID tersebut. Jika dua baris memiliki custom_id yang sama, Anda tidak dapat membedakan responsnya dengan pasti.

Kesimpulan

Anda sekarang memiliki alur lengkap: kemas prompt Anda ke dalam file JSONL, unggah, buat batch, lakukan polling status, dan ambil outputnya, semuanya dengan setengah biaya token dalam jendela waktu 24 jam. Setiap langkah mengembalikan objek yang dapat Anda verifikasi, jadi setelah bentuk JSONL dan loop polling sudah benar, sisanya hanyalah mekanis.

Sebelum Anda mengotomatisasinya, jalankan siklus hidup secara manual. Unduh Apidog untuk memvalidasi file permintaan Anda, melatih endpoint unggah, buat, polling, dan batalkan, serta menegaskan bidang objek batch sehingga baris yang salah format tidak pernah membuat Anda rugi perjalanan pulang-pergi 24 jam.