Berkas & batch

Membuat Batch Pesan

Membuat batch permintaan Pesan yang berjalan secara asinkron.

POST
/v1/messages/batches

Ringkasan

Kirim hingga 100.000 permintaan Pesan dalam satu panggilan. Batch berjalan secara asinkron. Respons akan langsung dikembalikan dengan processing_status diatur ke in_progress. Ambil batch hingga statusnya menjadi ended, kemudian dapatkan hasilnya.

Catatan

  • Setiap item dalam requests memiliki custom_id dan params. params menggunakan kolom yang sama dengan Buat Pesan, termasuk max_tokens. Item tidak dapat menggunakan speed: "fast".
  • custom_id terdiri dari 1 hingga 64 huruf, angka, garis bawah, atau tanda hubung, dan harus unik dalam batch tersebut.
  • Setiap model dalam batch harus tersedia untuk batch. TokenLab akan menolak seluruh permintaan dengan kode 400 jika model tidak tersedia, atau jika tidak ada satu rute pun yang dapat melayani semua model dalam batch tersebut.
  • TokenLab akan mencadangkan estimasi biaya saat menerima batch dan mengembalikan 402 jika saldo tidak mencukupi. Setelah batch berakhir, TokenLab akan menyelesaikan penggunaan untuk permintaan yang berhasil. Harga batch mungkin berbeda dari harga sinkron.
  • Jika suatu item mereferensikan konten file_id, kirim anthropic-beta: files-api-2025-04-14.
  • Kirim Idempotency-Key untuk mencoba kembali permintaan pembuatan yang mengalami timeout dengan aman. Lihat Coba kembali dengan aman menggunakan idempotency key.

Contoh

Permintaan

cURL
curl -X POST "https://api.tokenlab.sh/v1/messages/batches" \
  -H "x-api-key: sk-your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Idempotency-Key: 6f1c2a9e-0b7d-4c1e-9a53-2d9f3a1b7c10" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {
        "custom_id": "request-1",
        "params": {
          "model": "claude-sonnet-5",
          "max_tokens": 1024,
          "messages": [{"role": "user", "content": "Hello, Claude!"}]
        }
      },
      {
        "custom_id": "request-2",
        "params": {
          "model": "claude-sonnet-5",
          "max_tokens": 1024,
          "messages": [{"role": "user", "content": "Name three colors."}]
        }
      }
    ]
  }'

Contoh respons

Respons

200 OK
{
  "id": "msgbatch_01ABC123",
  "type": "message_batch",
  "processing_status": "in_progress",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2026-11-01T10:00:00Z",
  "expires_at": "2026-11-02T10:00:00Z",
  "cancel_initiated_at": null,
  "archived_at": null,
  "results_url": null
}

Bidang penting

idstring
ID batch pesan. Gunakan ID ini untuk mengambil, membatalkan, atau menghapus batch dan untuk mendapatkan hasilnya.
processing_statusstring
in_progress, canceling, atau ended.
request_countsobject
Jumlah permintaan yang sedang processing, succeeded, errored, canceled, atau expired.
expires_atstring
Waktu kedaluwarsa batch. Permintaan yang belum selesai pada waktu tersebut akan berakhir sebagai expired.
results_urlstring|null
URL hasil. Nilainya null sampai batch berakhir.

Otorisasi

BearerAuth
AuthorizationBearer <token>

Autentikasi API Key. Buat atau kelola API key di Dashboard > API > API Keys.

Lokasi: header

Header

X-TokenLab-Delivery-Policy?string

Kebijakan Pengiriman per-permintaan. Menggantikan default API key dan Workspace. Secara otomatis mencoba TokenLab Verified terlebih dahulu dan dapat beralih satu kali ke Official saja sebelum output, penerimaan permintaan, atau pembuatan sumber daya persisten.

Nilai yang tersedia

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

Kunci opsional yang membuat permintaan pembuatan aman untuk dicoba ulang. Kirim nilai unik baru, seperti UUID, untuk setiap tugas. Percobaan ulang dengan kunci dan body yang sama akan mengembalikan hasil dari permintaan pembuatan asli, biasanya berupa tugas asli, dan tidak akan membuat, mengirim, atau mengenakan biaya untuk tugas kedua. Body yang berbeda dengan kunci yang sudah diterima akan ditolak dengan 409. Kunci yang lebih panjang dari 255 karakter akan diabaikan, dan permintaan tersebut tidak akan memiliki perlindungan idempotensi. Lihat Retry safely with an idempotency key.

Panjang1 <= length <= 255

Body permintaan

application/json

Respons

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json