Batches

Batch memproses banyak request asinkron (selesai dalam ≤ 24 jam) — cocok untuk evaluasi, klasifikasi massal, atau backfill. Sistem batch dijalankan sendiri (bukan diteruskan ke Batch API provider), dan setiap request ditagih saat selesai dengan harga normal — tanpa diskon batch.

Aturan umum kedua dialek:

• Maks 10.000 request atau 256 MiB per batch; model setiap request wajib ada di katalog (divalidasi sebelum diterima).
• Saldo harus > 0 saat create (402 bila tidak). Saldo habis di tengah jalan → sisa request gagal (billing_error / insufficient_quota), batch tetap diselesaikan.
• expires_at = created_at + 24 jam; yang belum diproses saat itu → expired. Hasil disimpan 29 hari.
• Cancel: request yang belum dikerjakan → canceled; yang sedang jalan dibiarkan selesai.
• Error dari upstream di hasil memakai pesan generik per status, misalnya Request ditolak upstream. (invalid_request) atau Upstream gagal, coba lagi sebentar. (upstream_error). Isi error dari penyedia model tidak pernah masuk file hasil.

Dialek Anthropic — /v1/messages/batches

curl <API>/v1/messages/batches \
  -H "x-api-key: $NGODING_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {
        "custom_id": "req-1",
        "params": {
          "model": "claude-haiku-4-5",
          "max_tokens": 64,
          "messages": [{"role": "user", "content": "Ringkas: fotosintesis."}]
        }
      }
    ]
  }'

params = body Messages biasa tanpa stream. custom_id unik per batch (1–64 karakter [A-Za-z0-9_-]).

Alur: POST /v1/messages/batches → poll GET /v1/messages/batches/{id} sampai processing_status: ended → ambil GET /v1/messages/batches/{id}/results (JSONL {custom_id, result}). Batal: POST …/{id}/cancel. Hapus: DELETE …/{id} (hanya bila ended).

Dialek OpenAI — /v1/batches

1. Tulis input JSONL ({custom_id, method: "POST", url, body}), upload sebagai file via Files.
2. POST /v1/batches dengan {input_file_id, endpoint: "/v1/chat/completions" | "/v1/responses", completion_window: "24h"}.
3. Poll GET /v1/batches/{id} sampai status terminal (completed, failed, expired, cancelled) — jangan berhenti di finalizing: batch yang selesai melewati finalizing dulu, dan output_file_id/error_file_id baru terisi atomik bersama status final. Selama validating, in_progress, finalizing, atau cancelling, teruskan polling.

Batal: POST /v1/batches/{id}/cancel. Output JSONL tersimpan sebagai file purpose: batch_output — unduh lewat output_file_id (atau error_file_id bila gagal sebagian).

Server tool

Request di dalam batch boleh memakai server tool seperti request biasa: web_search, web_fetch, dan x_search di Messages; web_search (termasuk buka halaman) dan x_search di Responses; web_search_options di Chat. Setiap request menjalankan loop server tool yang sama dengan request non-stream biasa, termasuk batas iterasi, max_tool_calls, dan tahanan credit per iterasi.

• Hasil. Sama dengan respons non-stream biasa: blok server_tool_use dan web_search_tool_result di Messages; item web_search_call / x_search_call di Responses, dengan anotasi url_citation di teks jawaban; dan message.annotations berisi url_citation di Chat.
• Tagihan. Satu request batch = satu baris pemakaian (endpoint = 'batch'): token semua iterasi ditambah credit tool, dengan harga normal yang sama dengan request biasa (tanpa diskon batch). Tool yang error tidak ditagih; request yang gagal tanpa pemakaian tidak tercatat.
• Credit habis di tengah loop. Request berhenti seperti request biasa dan tetap succeeded: stop_reason: "pause_turn" di Messages, status: "incomplete" di Responses, finish_reason: "length" di Chat. Request berikutnya tetap dikerjakan selama saldo masih > 0.
• Upstream gagal di tengah loop. Bila upstream menolak dengan error di iterasi pertama, request gagal tanpa tagihan. Setelah iterasi pertama:
  • Messages: hasil succeeded dengan stop_reason: "pause_turn" berisi konten yang sudah jadi. Lanjutkan dengan request baru seperti di pause_turn.
  • Responses dan Chat: request gagal (masuk error_file_id) dengan kode seperti upstream_error. Token dan tool dari iterasi yang sudah selesai tetap ditagih.
  • Jawaban upstream yang rusak, di iterasi mana pun, membuat request gagal (upstream_error) dan ditagih dari estimasi, sama seperti request biasa.
• Tool tidak tersedia. Request itu gagal dengan kode yang sama seperti request biasa, dan request lain di batch tetap jalan: unsupported_tool bila tool sedang dimatikan atau mesinnya belum aktif, unsupported_parameter untuk web_search_options di Chat saat server tool dimatikan seluruhnya, unsupported_content bila model tidak mendukung tool calling.
• Batas panggilan tool. Batas 60 panggilan tool per menit per akun dihitung bersama request biasa. Panggilan yang lewat batas menjadi hasil tool too_many_requests yang dibaca model, sedangkan token jawabannya tetap ditagih.
• Saldo. Saldo habis saat request ber-server-tool akan mulai → sisa request gagal, sesuai aturan umum di atas.

Penagihan

Tiap request batch memakai router + reservasi saldo yang sama dengan request biasa, dicatat dengan endpoint = 'batch' dan batch_id-nya. Request ber-server-tool tetap satu baris (lihat Server tool). Ganti <API> dengan https://api.ngoding.in. Referensi lengkap: OpenAPI: Batches.

Coba langsung: referensi interaktif + try-it di OpenAPI — request dikirim dari browser ke https://api.ngoding.in, kuncimu hanya disimpan di sessionStorage tab ini (hilang saat tab ditutup) dan tidak pernah dicatat.