Pemrosesan batch adalah pendekatan yang kuat untuk menangani volume besar permintaan secara efisien. Alih-alih memproses permintaan satu per satu dengan respons langsung, pemrosesan batch memungkinkan Anda mengirimkan beberapa permintaan sekaligus untuk pemrosesan asinkron. Pola ini sangat berguna ketika:

• Anda perlu memproses volume besar data
• Respons langsung tidak diperlukan
• Anda ingin mengoptimalkan efisiensi biaya
• Anda menjalankan evaluasi atau analisis skala besar

Message Batches API adalah implementasi pertama Anthropic dari pola ini.

Message Batches API

Message Batches API adalah cara yang kuat dan hemat biaya untuk memproses secara asinkron volume besar permintaan Messages. Pendekatan ini sangat cocok untuk tugas yang tidak memerlukan respons langsung, dengan sebagian besar batch selesai dalam waktu kurang dari 1 jam sambil mengurangi biaya sebesar 50% dan meningkatkan throughput.

Anda dapat menjelajahi referensi API secara langsung, selain panduan ini.

Cara kerja Message Batches API

Ketika Anda mengirimkan permintaan ke Message Batches API:

1. Sistem membuat Message Batch baru dengan permintaan Messages yang disediakan.
2. Batch kemudian diproses secara asinkron, dengan setiap permintaan ditangani secara independen.
3. Anda dapat melakukan polling untuk status batch dan mengambil hasil ketika pemrosesan telah selesai untuk semua permintaan.

Ini sangat berguna untuk operasi massal yang tidak memerlukan hasil langsung, seperti:

• Evaluasi skala besar: Proses ribuan kasus uji secara efisien.
• Moderasi konten: Analisis volume besar konten buatan pengguna secara asinkron.
• Analisis data: Hasilkan wawasan atau ringkasan untuk dataset besar.
• Pembuatan konten massal: Buat jumlah besar teks untuk berbagai tujuan (misalnya, deskripsi produk, ringkasan artikel).

Batasan batch

• Message Batch dibatasi hingga 100.000 permintaan Message atau 256 MB ukuran, mana pun yang tercapai terlebih dahulu.
• Sistem memproses setiap batch secepat mungkin, dengan sebagian besar batch selesai dalam 1 jam. Anda dapat mengakses hasil batch ketika semua pesan telah selesai atau setelah 24 jam, mana pun yang lebih dulu. Batch kedaluwarsa jika pemrosesan tidak selesai dalam 24 jam.
• Hasil batch tersedia selama 29 hari setelah pembuatan. Setelah itu, Anda masih dapat melihat Batch, tetapi hasilnya tidak akan lagi tersedia untuk diunduh.
• Batch dicakup oleh Workspace. Anda dapat melihat semua batch (dan hasilnya) yang dibuat dalam Workspace yang menjadi milik kunci API Anda.
• Batas laju berlaku untuk permintaan HTTP Batches API dan jumlah permintaan dalam batch yang menunggu untuk diproses. Lihat batas laju Message Batches API. Selain itu, pemrosesan dapat diperlambat berdasarkan permintaan saat ini dan volume permintaan Anda. Dalam hal itu, Anda mungkin melihat lebih banyak permintaan kedaluwarsa setelah 24 jam.
• Karena throughput tinggi dan pemrosesan bersamaan, batch dapat sedikit melampaui batas pengeluaran yang dikonfigurasi Workspace Anda.

Model yang didukung

Semua model aktif mendukung Message Batches API.

Apa yang dapat di-batch

Permintaan apa pun yang dapat Anda buat ke Messages API dapat disertakan dalam batch. Ini termasuk:

• Visi
• Penggunaan alat
• Pesan sistem
• Percakapan multi-putaran
• Fitur beta apa pun

Karena setiap permintaan dalam batch diproses secara independen, Anda dapat mencampur berbagai jenis permintaan dalam satu batch.

Harga

Batches API menawarkan penghematan biaya yang signifikan. Semua penggunaan dikenakan biaya pada 50% dari harga API standar.

Cara menggunakan Message Batches API

Siapkan dan buat batch Anda

Message Batch terdiri dari daftar permintaan untuk membuat Message. Bentuk permintaan individual terdiri dari:

• custom_id unik untuk mengidentifikasi permintaan Messages. Harus 1 hingga 64 karakter dan hanya berisi karakter alfanumerik, tanda hubung, dan garis bawah (cocok dengan ^[a-zA-Z0-9_-]{1,64}$).
• Objek params dengan parameter Messages API standar

Anda dapat membuat batch dengan melewatkan daftar ini ke parameter requests:

Dalam contoh ini, dua permintaan terpisah di-batch bersama untuk pemrosesan asinkron. Setiap permintaan memiliki custom_id unik dan berisi parameter standar yang akan Anda gunakan untuk panggilan Messages API.

Ketika batch pertama kali dibuat, respons akan memiliki status pemrosesan in_progress.

{
  "id": "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
  "type": "message_batch",
  "processing_status": "in_progress",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2024-09-24T18:37:24.100435Z",
  "expires_at": "2024-09-25T18:37:24.100435Z",
  "cancel_initiated_at": null,
  "results_url": null
}

Melacak batch Anda

Bidang processing_status Message Batch menunjukkan tahap pemrosesan batch. Dimulai sebagai in_progress, kemudian diperbarui ke ended setelah semua permintaan dalam batch selesai diproses, dan hasil siap. Anda dapat memantau status batch Anda dengan mengunjungi Console, atau menggunakan endpoint pengambilan.

Polling untuk penyelesaian Message Batch

Untuk melakukan polling Message Batch, Anda memerlukan id-nya, yang disediakan dalam respons saat membuat batch atau dengan membuat daftar batch. Anda dapat mengimplementasikan loop polling yang memeriksa status batch secara berkala hingga pemrosesan selesai:

Membuat daftar semua Message Batches

Anda dapat membuat daftar semua Message Batches di Workspace Anda menggunakan endpoint daftar. API mendukung paginasi, secara otomatis mengambil halaman tambahan sesuai kebutuhan:

Mengambil hasil batch

Setelah pemrosesan batch selesai, setiap permintaan Messages dalam batch memiliki hasil. Ada 4 jenis hasil:

Anda akan melihat gambaran umum hasil Anda dengan request_counts batch, yang menunjukkan berapa banyak permintaan yang mencapai masing-masing dari empat status ini.

Hasil batch tersedia untuk diunduh di properti results_url pada Message Batch, dan jika izin organisasi memungkinkan, di Console. Karena ukuran hasil yang berpotensi besar, disarankan untuk streaming hasil kembali daripada mengunduhnya sekaligus.

Hasil berada dalam format .jsonl, di mana setiap baris adalah objek JSON yang valid yang mewakili hasil dari satu permintaan dalam Message Batch. Untuk setiap hasil yang di-stream, Anda dapat melakukan sesuatu yang berbeda tergantung pada custom_id dan jenis hasilnya. Berikut adalah contoh set hasil:

{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-4-7","content":[{"type":"text","text":"Hello again! It's nice to see you. How can I assist you today? Is there anything specific you'd like to chat about or any questions you have?"}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":11,"output_tokens":36}}}}
{"custom_id":"my-first-request","result":{"type":"succeeded","message":{"id":"msg_01FqfsLoHwgeFbguDgpz48m7","type":"message","role":"assistant","model":"claude-opus-4-7","content":[{"type":"text","text":"Hello! How can I assist you today? Feel free to ask me any questions or let me know if there's anything you'd like to chat about."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":34}}}}

Jika hasil Anda memiliki kesalahan, result.error akan diatur ke bentuk kesalahan standar.

Membatalkan Message Batch

Anda dapat membatalkan Message Batch yang sedang diproses menggunakan endpoint pembatalan. Segera setelah pembatalan, processing_status batch akan menjadi canceling. Anda dapat menggunakan teknik polling yang sama seperti yang dijelaskan di atas untuk menunggu sampai pembatalan selesai. Batch yang dibatalkan berakhir dengan status ended dan mungkin berisi hasil parsial untuk permintaan yang diproses sebelum pembatalan.

Respons akan menunjukkan batch dalam status canceling:

{
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message_batch",
  "processing_status": "canceling",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2024-09-24T18:37:24.100435Z",
  "expires_at": "2024-09-25T18:37:24.100435Z",
  "cancel_initiated_at": "2024-09-24T18:39:03.114875Z",
  "results_url": null
}

Menggunakan prompt caching dengan Message Batches

Message Batches API mendukung prompt caching, memungkinkan Anda untuk berpotensi mengurangi biaya dan waktu pemrosesan untuk permintaan batch. Diskon harga dari prompt caching dan Message Batches dapat ditumpuk, memberikan penghematan biaya yang lebih besar ketika kedua fitur digunakan bersama. Namun, karena permintaan batch diproses secara asinkron dan bersamaan, cache hits disediakan dengan dasar best-effort. Pengguna biasanya mengalami tingkat cache hit berkisar dari 30% hingga 98%, tergantung pada pola lalu lintas mereka.

Untuk memaksimalkan kemungkinan cache hits dalam permintaan batch Anda:

1. Sertakan blok cache_control yang identik di setiap permintaan Message dalam batch Anda
2. Pertahankan aliran permintaan yang stabil untuk mencegah entri cache kedaluwarsa setelah masa hidup 5 menit mereka
3. Struktur permintaan Anda untuk berbagi sebanyak mungkin konten yang di-cache

Contoh implementasi prompt caching dalam batch:

Dalam contoh ini, kedua permintaan dalam batch mencakup pesan sistem yang identik dan teks lengkap Pride and Prejudice yang ditandai dengan cache_control untuk meningkatkan kemungkinan cache hits.

Output yang diperluas (beta)

Header beta output-300k-2026-03-24 menaikkan batas max_tokens menjadi 300.000 untuk permintaan batch menggunakan Claude Opus 4.7, Claude Opus 4.6, atau Claude Sonnet 4.6. Sertakan header untuk menghasilkan output jauh lebih panjang dari batas standar (64k hingga 128k tergantung model) dalam satu putaran.

Gunakan output yang diperluas untuk generasi bentuk panjang seperti draf panjang buku dan dokumentasi teknis, ekstraksi data terstruktur yang lengkap, scaffold generasi kode besar, dan rantai penalaran panjang.

Generasi 300k-token tunggal dapat memakan waktu lebih dari satu jam untuk diselesaikan, jadi rencanakan pengiriman batch Anda dengan jendela pemrosesan 24 jam dalam pikiran. Harga batch standar (50% dari harga API standar) berlaku.

Praktik terbaik untuk batching yang efektif

Untuk memanfaatkan Batches API sebaik-baiknya:

• Pantau status pemrosesan batch secara teratur dan implementasikan logika retry yang sesuai untuk permintaan yang gagal.
• Gunakan nilai custom_id yang bermakna untuk dengan mudah mencocokkan hasil dengan permintaan, karena urutan tidak dijamin.
• Pertimbangkan untuk memecah dataset yang sangat besar menjadi beberapa batch untuk manajemen yang lebih baik.
• Jalankan percobaan satu bentuk permintaan dengan Messages API untuk menghindari kesalahan validasi.

Pemecahan masalah untuk masalah umum

Jika mengalami perilaku yang tidak terduga:

• Verifikasi bahwa ukuran total permintaan batch tidak melebihi 256 MB. Jika ukuran permintaan terlalu besar, Anda mungkin mendapatkan kesalahan 413 request_too_large.
• Periksa bahwa Anda menggunakan model yang didukung untuk semua permintaan dalam batch.
• Pastikan setiap permintaan dalam batch memiliki custom_id yang unik.
• Pastikan bahwa kurang dari 29 hari telah berlalu sejak waktu batch created_at (bukan ended_at pemrosesan). Jika lebih dari 29 hari telah berlalu, hasil tidak akan lagi dapat dilihat.
• Konfirmasi bahwa batch belum dibatalkan.

Perhatikan bahwa kegagalan satu permintaan dalam batch tidak mempengaruhi pemrosesan permintaan lain.

Penyimpanan batch dan privasi

• Isolasi Workspace: Batch terisolasi dalam Workspace tempat mereka dibuat. Mereka hanya dapat diakses oleh kunci API yang terkait dengan Workspace itu, atau pengguna dengan izin untuk melihat batch Workspace di Console.

• Ketersediaan hasil: Hasil batch tersedia selama 29 hari setelah batch dibuat, memberikan waktu yang cukup untuk pengambilan dan pemrosesan.

Retensi data

Pemrosesan batch menyimpan data permintaan dan respons hingga 29 hari setelah pembuatan batch. Anda dapat menghapus batch pesan kapan saja setelah pemrosesan menggunakan endpoint DELETE /v1/messages/batches/{batch_id}. Untuk menghapus batch yang sedang berlangsung, batalkan terlebih dahulu. Pemrosesan asinkron memerlukan penyimpanan sisi server dari input dan output hingga penyelesaian batch dan pengambilan hasil.

Untuk kelayakan ZDR di semua fitur, lihat API dan retensi data.

FAQ