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

Anda perlu memproses volume data yang besar
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.

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

Message Batches API

Message Batches API adalah cara yang powerful dan hemat biaya untuk memproses volume besar permintaan Messages secara asinkron. Pendekatan ini sangat cocok untuk tugas-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 mengirim permintaan ke Message Batches API:

Sistem membuat Message Batch baru dengan permintaan Messages yang diberikan.
Batch kemudian diproses secara asinkron, dengan setiap permintaan ditangani secara independen.
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 segera, seperti:

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

Batasan batch

Sebuah Message Batch dibatasi hingga 100.000 permintaan Message atau 256 MB dalam ukuran, mana yang tercapai lebih dulu.
Sistem memproses setiap batch secepat mungkin, dengan sebagian besar batch selesai dalam 1 jam. Anda akan dapat mengakses hasil batch ketika semua pesan telah selesai atau setelah 24 jam, mana yang lebih dulu. Batch akan 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 memiliki cakupan pada sebuah Workspace. Anda dapat melihat semua batch (dan hasilnya) yang dibuat dalam Workspace tempat kunci API Anda berada.
Batas rate berlaku untuk permintaan HTTP Batches API dan jumlah permintaan dalam batch yang menunggu untuk diproses. Lihat Batas rate Message Batches API. Selain itu, pemrosesan mungkin diperlambat berdasarkan permintaan saat ini dan volume permintaan Anda. Dalam kasus tersebut, Anda mungkin melihat lebih banyak permintaan yang kedaluwarsa setelah 24 jam.
Karena throughput tinggi dan pemrosesan bersamaan, batch mungkin sedikit melebihi 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:

Vision
Penggunaan tool
Pesan sistem
Percakapan multi-giliran
Fitur beta apa pun

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

Karena batch dapat memakan waktu lebih dari 5 menit untuk diproses, pertimbangkan menggunakan durasi cache 1 jam dengan prompt caching untuk tingkat cache hit yang lebih baik saat memproses batch dengan konteks bersama.

Harga

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

Model	Batch input	Batch output
Claude Opus 4.6	$2.50 / MTok	$12.50 / MTok
Claude Opus 4.5	$2.50 / MTok	$12.50 / MTok
Claude Opus 4.1	$7.50 / MTok	$37.50 / MTok
Claude Opus 4	$7.50 / MTok	$37.50 / MTok
Claude Sonnet 4.6	$1.50 / MTok	$7.50 / MTok
Claude Sonnet 4.5	$1.50 / MTok	$7.50 / MTok
Claude Sonnet 4	$1.50 / MTok	$7.50 / MTok
Claude Sonnet 3.7 (deprecated)	$1.50 / MTok	$7.50 / MTok
Claude Haiku 4.5

Cara menggunakan Message Batches API

Siapkan dan buat batch Anda

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

Sebuah custom_id unik untuk mengidentifikasi permintaan Messages
Sebuah objek params dengan parameter Messages API standar

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

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

Uji permintaan batch Anda dengan Messages API

Validasi objek params untuk setiap permintaan pesan dilakukan secara asinkron, dan kesalahan validasi dikembalikan ketika pemrosesan seluruh batch telah selesai. Anda dapat memastikan bahwa Anda membangun input dengan benar dengan memverifikasi bentuk permintaan Anda dengan Messages API terlebih dahulu.

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

JSON

{
  "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

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

Polling untuk penyelesaian Message Batch

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

Mendaftar semua Message Batch

Anda dapat mendaftar semua Message Batch di Workspace Anda menggunakan endpoint list. API mendukung pagination, secara otomatis mengambil halaman tambahan sesuai kebutuhan:

Mengambil hasil batch

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

Jenis Hasil	Deskripsi
`succeeded`	Permintaan berhasil. Termasuk hasil pesan.
`errored`	Permintaan mengalami kesalahan dan pesan tidak dibuat. Kemungkinan kesalahan termasuk permintaan tidak valid dan kesalahan server internal. Anda tidak akan ditagih untuk permintaan ini.
`canceled`	Pengguna membatalkan batch sebelum permintaan ini dapat dikirim ke model. Anda tidak akan ditagih untuk permintaan ini.
`expired`	Batch mencapai kedaluwarsa 24 jam sebelum permintaan ini dapat dikirim ke model. Anda tidak akan ditagih untuk permintaan ini.

Anda akan melihat ikhtisar 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 mengizinkan, di Console. Karena ukuran hasil yang berpotensi besar, disarankan untuk streaming hasil daripada mengunduh semuanya sekaligus.

Hasilnya akan 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:

.jsonl file

{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-4-6","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-6","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-nya akan diatur ke bentuk kesalahan standar.

Hasil batch mungkin tidak sesuai dengan urutan input

Hasil batch dapat dikembalikan dalam urutan apa pun, dan mungkin tidak sesuai dengan urutan permintaan saat batch dibuat. Dalam contoh di atas, hasil untuk permintaan batch kedua dikembalikan sebelum yang pertama. Untuk mencocokkan hasil dengan permintaan yang sesuai dengan benar, selalu gunakan field custom_id.

Membatalkan Message Batch

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

Respons akan menampilkan batch dalam status canceling:

JSON

{
  "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, yang memungkinkan Anda berpotensi mengurangi biaya dan waktu pemrosesan untuk permintaan batch. Diskon harga dari prompt caching dan Message Batches dapat digabungkan, memberikan penghematan biaya yang lebih besar ketika kedua fitur digunakan bersama. Namun, karena permintaan batch diproses secara asinkron dan bersamaan, cache hit diberikan berdasarkan upaya terbaik. Pengguna biasanya mengalami tingkat cache hit antara 30% hingga 98%, tergantung pada pola lalu lintas mereka.

Untuk memaksimalkan kemungkinan cache hit dalam permintaan batch Anda:

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

Contoh implementasi prompt caching dalam batch:

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

Praktik terbaik untuk batching yang efektif

Untuk mendapatkan hasil maksimal dari Batches API:

Pantau status pemrosesan batch secara teratur dan terapkan logika percobaan ulang yang sesuai untuk permintaan yang gagal.
Gunakan nilai custom_id yang bermakna untuk memudahkan pencocokan hasil dengan permintaan, karena urutan tidak dijamin.
Pertimbangkan untuk memecah dataset yang sangat besar menjadi beberapa batch untuk kemudahan pengelolaan yang lebih baik.
Lakukan dry run satu bentuk permintaan dengan Messages API untuk menghindari kesalahan validasi.

Pemecahan masalah umum

Jika mengalami perilaku yang tidak terduga:

Verifikasi bahwa total ukuran permintaan batch tidak melebihi 256 MB. Jika ukuran permintaan terlalu besar, Anda mungkin mendapatkan error 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 belum lebih dari 29 hari sejak waktu created_at batch (bukan waktu ended_at pemrosesan). Jika lebih dari 29 hari telah berlalu, hasil tidak akan dapat dilihat lagi.
Konfirmasi bahwa batch belum dibatalkan.

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

Penyimpanan dan privasi batch

Isolasi Workspace: Batch diisolasi dalam Workspace tempat mereka dibuat. Mereka hanya dapat diakses oleh kunci API yang terkait dengan Workspace tersebut, 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 message batch kapan saja setelah pemrosesan menggunakan endpoint DELETE /v1/messages/batches/{batch_id}. 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

curl https://api.anthropic.com/v1/messages/batches \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "requests": [
        {
            "custom_id": "my-first-request",
            "params": {
                "model": "claude-opus-4-6",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hello, world"}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-6",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hi again, friend"}
                ]
            }
        }
    ]
}'

import anthropic
import time

client = anthropic.Anthropic()

message_batch = None
while True:
    message_batch = client.messages.batches.retrieve(MESSAGE_BATCH_ID)
    if message_batch.processing_status == "ended":
        break

    print(f"Batch {MESSAGE_BATCH_ID} is still processing...")
    time.sleep(60)
print(message_batch)

import anthropic

client = anthropic.Anthropic()

# Secara otomatis mengambil lebih banyak halaman sesuai kebutuhan.
for message_batch in client.messages.batches.list(limit=20):
    print(message_batch)

#!/bin/sh
curl "https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  | grep -o '"results_url":[[:space:]]*"[^"]*"' \
  | cut -d'"' -f4 \
  | while read -r url; do
    curl -s "$url" \
      --header "anthropic-version: 2023-06-01" \
      --header "x-api-key: $ANTHROPIC_API_KEY" \
      | sed 's/}{/}\n{/g' \
      | while IFS= read -r line
    do
      result_type=$(echo "$line" | sed -n 's/.*"result":[[:space:]]*{[[:space:]]*"type":[[:space:]]*"\([^"]*\)".*/\1/p')
      custom_id=$(echo "$line" | sed -n 's/.*"custom_id":[[:space:]]*"\([^"]*\)".*/\1/p')
      error_type=$(echo "$line" | sed -n 's/.*"error":[[:space:]]*{[[:space:]]*"type":[[:space:]]*"\([^"]*\)".*/\1/p')

      case "$result_type" in
        "succeeded")
          echo "Success! $custom_id"
          ;;
        "errored")
          if [ "$error_type" = "invalid_request" ]; then
            # Request body must be fixed before re-sending request
            echo "Validation error: $custom_id"
          else
            # Request can be retried directly
            echo "Server error: $custom_id"
          fi
          ;;
        "expired")
          echo "Expired: $line"
          ;;
      esac
    done
  done

curl https://api.anthropic.com/v1/messages/batches \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "requests": [
        {
            "custom_id": "my-first-request",
            "params": {
                "model": "claude-opus-4-6",
                "max_tokens": 1024,
                "system": [
                    {
                        "type": "text",
                        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
                    },
                    {
                        "type": "text",
                        "text": "<the entire contents of Pride and Prejudice>",
                        "cache_control": {"type": "ephemeral"}
                    }
                ],
                "messages": [
                    {"role": "user", "content": "Analyze the major themes in Pride and Prejudice."}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-6",
                "max_tokens": 1024,
                "system": [
                    {
                        "type": "text",
                        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
                    },
                    {
                        "type": "text",
                        "text": "<the entire contents of Pride and Prejudice>",
                        "cache_control": {"type": "ephemeral"}
                    }
                ],
                "messages": [
                    {"role": "user", "content": "Write a summary of Pride and Prejudice."}
                ]
            }
        }
    ]
}'

Message Batches API

Cara kerja Message Batches API

Batasan batch

Model yang didukung

Apa yang dapat di-batch

Harga

Cara menggunakan Message Batches API

Siapkan dan buat batch Anda

Melacak batch Anda

Polling untuk penyelesaian Message Batch

Mendaftar semua Message Batch

Mengambil hasil batch

Membatalkan Message Batch

Menggunakan prompt caching dengan Message Batches

Praktik terbaik untuk batching yang efektif

Pemecahan masalah umum

Penyimpanan dan privasi batch

Retensi data

FAQ

Berapa lama waktu yang dibutuhkan untuk memproses batch?

Apakah Batches API tersedia untuk semua model?

Bisakah saya menggunakan Message Batches API dengan fitur API lainnya?

Bagaimana Message Batches API mempengaruhi harga?

Bisakah saya memperbarui batch setelah dikirimkan?

Apakah ada batas rate Message Batches API dan apakah berinteraksi dengan batas rate Messages API?

Bagaimana cara menangani error dalam permintaan batch saya?

Bagaimana Message Batches API menangani privasi dan pemisahan data?

Bisakah saya menggunakan prompt caching di Message Batches API?