Claude Batch API: Jalankan Tugas Asinkron dengan Biaya Setengah

Jawaban singkat: Claude Batch API memproses permintaan Messages API secara asinkron dengan diskon 50% untuk token input maupun output. Anda mengirimkan hingga 100.000 permintaan (atau 256 MB) dalam satu panggilan, melakukan polling hingga batch selesai, lalu membaca hasil yang dikunci berdasarkan custom_id milik Anda sendiri. Sebagian besar batch selesai dalam waktu satu jam, dan batas maksimalnya adalah 24 jam.

Coba Apidog hari ini

Anda memiliki 40.000 tiket dukungan untuk diklasifikasikan, atau katalog produk untuk ditulis ulang, atau transkrip selama sebulan untuk diringkas. Tidak ada satu pun yang mendesak. Setiap panggilan tersebut tetap ditagih dengan harga penuh ketika Anda menjalankannya satu per satu, dan Anda menghabiskan sepanjang sore untuk mengawasi percobaan ulang terhadap batas laju Anda.

Claude Batch API ada tepat untuk bentuk pekerjaan seperti ini. Anda menyerahkan daftar permintaan kepada Anthropic, meninggalkannya, dan kembali ke file hasil yang biayanya hanya setengah dari biaya panggilan yang sama jika dilakukan secara sinkron. Tidak ada antrean yang perlu dijalankan, tidak ada penyetelan konkurensi, tidak ada logika backoff.

Panduan ini mencakup apa yang dilakukan endpoint batch, berapa biayanya, cara mengirim dan mengumpulkan pekerjaan, serta cara membiarkan agen coding Anda menguji seluruh prosesnya dengan Apidog CLI sebelum Anda mengarahkannya ke data nyata.

Apa itu Claude Batch API?

Claude Batch API adalah endpoint asinkron di /v1/messages/batches yang menerima banyak permintaan Messages API dalam satu pengiriman dan mengembalikan hasilnya setelah pemrosesan berakhir. API ini menukar latensi dengan diskon 50%. Anthropic mendokumentasikannya di bawah batch processing.

Batasan yang perlu Anda perhitungkan saat merancang:

• Ukuran: hingga 100.000 permintaan atau 256 MB per batch, mana pun yang tercapai lebih dulu.
• Waktu: sebagian besar batch selesai dalam waktu satu jam; 24 jam adalah waktu maksimal sebelum permintaan yang belum selesai kedaluwarsa.
• Retensi: hasil tetap tersedia selama 29 hari setelah batch dibuat.
• Kesetaraan fitur: vision, penggunaan tool, prompt sistem, dan prompt caching semuanya berfungsi di dalam batch.
• Urutan: hasil dikembalikan dalam urutan apa pun, jadi kunci berdasarkan custom_id dan jangan pernah berdasarkan posisi.

Poin terakhir itulah yang sering menjebak orang. Batch adalah kumpulan, bukan antrean.

Berapa biaya Claude Batch API

Diskonnya adalah 50% tetap untuk token input maupun output, yang diterapkan pada model apa pun yang disebutkan oleh setiap permintaan. Anda dapat mencampur model di dalam satu batch, sehingga pengklasifikasi murah dan peringkas mahal dapat berjalan bersamaan.

Model	Input / output standar per MTok	Input / output batch per MTok
Claude Opus 5.5	$4.00 / $20.00	$2.00 / $10.00
Claude Sonnet 5.5	$2.00 / $10.00	$1.00 / $5.00
Claude Haiku 5.5 (prompt hingga 100K)	$0.10 / $0.50	$0.05 / $0.25
Claude Haiku 5.5 (prompt di atas 100K)	$0.50 / $2.50	$0.25 / $1.25

Baca baris Haiku dengan cermat. Haiku 5.5 menetapkan harga berdasarkan ukuran prompt, jadi satu prompt yang melewati 100.000 token ditagih 5x tarif prompt pendek, terlepas dari diskon batch atau tidak. Perkirakan pekerjaan Haiku dengan konteks panjang pada $0.25 / $1.25, bukan $0.05 / $0.25. Periksa halaman harga Anthropic sebelum Anda membuat perkiraan berdasarkan angka-angka ini, dan baca uraian kami tentang ke mana pengeluaran Claude API pergi jika tagihan adalah alasan Anda berada di sini.

Harga batch juga dapat digabungkan dengan prompt caching, di situlah penghematan sesungguhnya berada. Selengkapnya di bawah ini.

Kirim batch pertama Anda

Pasang Python SDK resmi dan buat daftar permintaan. Masing-masing membawa custom_id yang Anda pilih dan objek params yang tampak persis seperti panggilan messages.create() biasa.

import anthropic
from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request

client = anthropic.Anthropic()

tickets = [
    "Card declined three times, support chat timed out.",
    "Love the new dashboard, the export button is hidden though.",
    "Webhook stopped firing after the 2.4 upgrade.",
]

batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id=f"ticket-{i}",
            params=MessageCreateParamsNonStreaming(
                model="claude-haiku-5-5",
                max_tokens=1024,
                output_config={"effort": "low"},
                messages=[{
                    "role": "user",
                    "content": f"Label this ticket billing, bug, or praise. One word.\n\n{text}",
                }],
            ),
        )
        for i, text in enumerate(tickets)
    ]
)

print(batch.id, batch.processing_status)

Buatlah custom_id yang bermakna. Kunci utama basis data atau jalur file akan menghemat penggabungan nanti, dan itu satu-satunya hal yang menghubungkan hasil kembali ke inputnya.

Jika Anda lebih suka HTTP mentah, payload yang sama dikirim ke POST https://api.anthropic.com/v1/messages/batches dengan header x-api-key dan anthropic-version Anda. Referensi create a message batch memiliki skema lengkapnya.

Polling batch dan kumpulkan hasilnya

Ambil batch hingga processing_status terbaca ended, lalu alirkan hasilnya. Setiap hasil membawa custom_id yang Anda tetapkan dan result.type berupa succeeded, errored, canceled, atau expired.

import time

while True:
    batch = client.messages.batches.retrieve(batch.id)
    if batch.processing_status == "ended":
        break
    print("still working:", batch.request_counts.processing)
    time.sleep(30)

labels, retry = {}, []
for result in client.messages.batches.results(batch.id):
    if result.result.type == "succeeded":
        msg = result.result.message
        labels[result.custom_id] = next(b.text for b in msg.content if b.type == "text")
    elif result.result.type == "errored":
        retry.append(result.custom_id)

print(f"{len(labels)} labeled, {len(retry)} need another pass")

Dua mode kegagalan perlu penanganan terpisah. Error invalid_request berarti body permintaan salah, jadi perbaiki sebelum mengirim ulang. Apa pun selain itu adalah sisi server dan aman untuk dicoba ulang apa adanya. Hasil expired berarti jendela 24 jam tertutup sebelum permintaan tersebut dijalankan, dan Anda mengirim ulang permintaan itu juga.

Lakukan polling dengan pengatur waktu 30 hingga 60 detik. Menghantam endpoint retrieve setiap detik tidak memberi Anda apa pun dan tetap dihitung terhadap batas laju Claude API Anda.

Gabungkan harga batch dengan prompt caching

Keuntungan terbesar datang dari menggabungkan kedua diskon tersebut. Jika setiap permintaan dalam batch Anda berbagi prefiks panjang, panduan gaya, taksonomi, kontrak 40 halaman, tandai prefiks itu dengan cache_control dan kirim prefiks bertanda yang sama pada semua 10.000 permintaan.

shared_system = [
    {"type": "text", "text": "You are a support triage analyst."},
    {
        "type": "text",
        "text": taxonomy_document,          # thousands of tokens, identical every time
        "cache_control": {"type": "ephemeral"},
    },
]

Letakkan blok system itu pada setiap Request di dalam batch. Permintaan apa pun yang prefiksnya cocok dengan entri cache aktif byte per byte akan ditagih pada tarif cache-read untuk prefiks tersebut, dan diskon batch 50% berlaku untuk cache read maupun write. Jangan menganggarkan tingkat hit yang sempurna: sebuah batch memproses permintaannya secara bersamaan alih-alih berurutan, jadi cache hit di dalam satu batch bersifat best-effort. Panduan prompt caching Anthropic mencakup aturan prefiks: setiap byte yang berubah sebelum breakpoint Anda akan membatalkan semua yang ada setelahnya, jadi letakkan timestamp dan teks per-item setelah blok yang di-cache.

Biarkan Claude Code menguji endpoint dengan Apidog CLI

Sebelum Anda menghabiskan uang untuk 100.000 permintaan langsung, Anda menginginkan tes regresi pada siklus hidup batch: create, retrieve, results. Menulisnya secara manual di GUI itu lambat. Biarkan agen coding Anda melakukannya dengan Apidog CLI sebagai gantinya.

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install   # pick Claude Code when prompted

Lalu satu prompt ke Claude Code:

In Apidog project 4820193, create a test case for POST https://api.anthropic.com/v1/messages/batches
that submits two Haiku 5.5 requests with custom_id ticket-0 and ticket-1, asserts the response
has an id and processing_status, then polls GET /v1/messages/batches/{id} until processing_status
is ended. Run it against the anthropic-staging environment and summarize failures.

Agen membaca skema payload, memvalidasi JSON-nya sendiri, lalu membuat dan menjalankan test case:

apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file batch-case.json
apidog test-case create --project 4820193 --file batch-case.json
apidog run --test-case 77214 --project 4820193 -e 992301 -r cli,json

Kunci API Anda tetap berada di variabel lingkungan Apidog, sehingga tidak pernah masuk ke prompt atau repositori. Ganti reporter ke -r junit dan perintah yang sama berjalan di CI pada setiap merge, itulah penyiapan dalam panduan pipeline Apidog CLI kami. Jika Anda belum menghubungkan CLI ke agen Anda, mulailah dengan menggunakan Apidog CLI di Claude Code.

Kapan batch adalah pilihan yang salah

Beban kerja	Gunakan batch?	Alasan
Peringkasan log kemarin setiap malam	Ya	Tidak ada yang menunggu; diskon 50%
Mengisi ulang embedding atau label pada sebuah korpus	Ya	Sesuai dengan batas 100.000 permintaan
Menjalankan evaluasi pada rangkaian prompt	Ya	Hasil yang dikunci berdasarkan custom_id dipetakan ke ID pengujian
Respons UI obrolan	Tidak	Pengguna tidak akan menunggu satu jam
Loop agen yang membutuhkan jawaban terakhir untuk memilih langkah berikutnya	Tidak	Permintaan batch tidak dapat saling melihat
Permintaan yang harus memenuhi SLA 5 detik	Tidak	Tidak ada jaminan latensi di bawah 24 jam

Beberapa hal juga tidak dapat diterapkan. Fast mode tidak tersedia di Batch API, fallback penolakan sisi server ditolak di sana, dan pada Claude Opus 5.5 serta Claude Sonnet 5.5 sebuah tool_choice paksa bernilai any atau tool mengembalikan 400 di dalam batch persis seperti pada panggilan biasa. Gunakan tool_choice: auto dengan strict: true sebagai gantinya.

Jika Anda menjalankan infrastruktur multi-penyedia, pola yang sama juga ada di tempat lain: lihat OpenAI Batch API dan mode batch Gemini API. Bentuknya berbeda, ekonominya tidak.

FAQ

Apa itu Claude Batch API?

Ini adalah endpoint asinkron yang menjalankan permintaan Messages API standar secara massal dengan 50% dari harga token normal. Anda mengirimkan daftar permintaan dengan ID Anda sendiri, melakukan polling hingga batch berakhir, dan membaca hasilnya dalam waktu 29 hari.

Berapa biaya Claude Batch API?

Setengah dari tarif standar untuk input maupun output. Pada Claude Sonnet 5.5 itu adalah $1.00 per juta token input dan $5.00 per juta token output, dibandingkan $2.00 dan $10.00 secara sinkron.

Berapa lama sebuah batch Claude memakan waktu?

Sebagian besar batch selesai dalam waktu satu jam. Maksimalnya adalah 24 jam, setelah itu permintaan yang belum diproses mengembalikan hasil expired dan Anda mengirim ulang permintaan itu.

Bisakah saya menggunakan prompt caching di dalam batch?

Ya, dan diskonnya dapat digabungkan. Tandai prefiks bersama dengan cache_control, ulangi prefiks identik itu di setiap permintaan, dan cache read akan ditagih dengan sebagian kecil dari harga input di atas diskon batch.

Apa yang terjadi ketika satu permintaan dalam batch gagal?

Hanya permintaan itu yang gagal. Hasilnya membawa type: "errored" dengan objek error; sisanya tetap berhasil. Error validasi memerlukan payload yang diperbaiki, error server aman untuk dicoba ulang tanpa perubahan.

Bisakah saya membatalkan batch yang sedang berjalan?

Ya. client.messages.batches.cancel(batch_id) memindahkan batch ke canceling. Permintaan yang sudah selesai tetap menyimpan hasilnya; sisanya kembali sebagai canceled.

Apakah Batch API mendukung tool dan gambar?

Ya. Setiap fitur Messages API berfungsi di dalam batch, termasuk vision, definisi tool, dan prompt sistem. Pengecualiannya adalah fast mode, fallback sisi server, dan tool choice paksa pada model 5.5.

Penutup

Pemrosesan batch adalah penghematan gratis terbesar kedua di Claude API setelah prompt caching, dan tidak mengurangi kualitas sama sekali: model yang sama, fitur yang sama, setengah harga, dibayar dengan latensi yang mungkin tidak Anda gunakan. Kunci hasil Anda berdasarkan custom_id, cache prefiks bersama, dan tangani expired sebagai percobaan ulang bukan kegagalan.

Uji siklus hidupnya sebelum Anda menskalakannya. Pasang Apidog CLI, arahkan agen coding Anda ke endpoint batch, dan biarkan test case yang dihasilkan tetap berjalan di CI agar perubahan skema tidak pernah mengejutkan Anda pada 100.000 permintaan. Paket gratisnya mencakup 4 pengguna, dan Anda dapat mengunduh Apidog serta menjalankan test case pertama dalam beberapa menit.