Message Batches API: giảm 50% chi phí Claude cho việc không cần trả lời ngay

Không phải request nào gửi tới Claude cũng cần trả lời trong vài giây. Phân loại 10.000 ticket hỗ trợ, tóm tắt cả kho tài liệu, chạy bộ eval so sánh prompt, sinh mô tả cho hàng nghìn sản phẩm… đều là việc có thể chờ. Với nhóm việc này, Message Batches API cho phép gửi một lần cả lô request, xử lý bất đồng bộ, và chỉ tính 50% giá chuẩn.

Batch API là gì?

Đây là cách gọi Messages API theo lô: bạn gom nhiều request vào một batch, gửi lên, rồi quay lại lấy kết quả khi xử lý xong. Mỗi request trong lô được xử lý độc lập — một request lỗi không ảnh hưởng các request khác. Theo tài liệu chính thức, phần lớn batch hoàn thành trong dưới 1 giờ.

Thông số cần nhớ

Giá batch tham khảo (USD / 1 triệu token)

Giá theo trang Batch processing của Claude Docs tại thời điểm viết bài; luôn kiểm tra lại trước khi lập ngân sách.

Hỗ trợ và không hỗ trợ gì?

Mọi model đang hoạt động đều dùng được Batch API. Một batch có thể trộn nhiều kiểu request khác nhau, và hỗ trợ gần như mọi tính năng của Messages API: hình ảnh (vision), tool use (kể cả server tool như web search, web fetch, code execution, MCP connector), system prompt, hội thoại nhiều lượt, extended thinking, phần lớn tính năng beta và prompt caching.

Những tham số sẽ bị báo lỗi validation:

• stream: true — kết quả trả về dạng file, không stream.
• speed (fast mode) và fallbacks — chỉ có ý nghĩa với API đồng bộ.
• max_tokens: 0 (làm nóng cache) — cache sẽ hết hạn trước khi request sau kịp dùng.

Một điểm thú vị: với header beta output-300k-2026-03-24, request trong batch được nâng max_tokens lên tới 300.000 trên các model hỗ trợ — chỉ có ở Batch API, không có ở API đồng bộ.

Quy trình 4 bước (Python)

Bước 1 — Tạo batch

import anthropic
client = anthropic.Anthropic()

batch = client.messages.batches.create(requests=[
    {
        "custom_id": f"ticket-{t['id']}",
        "params": {
            "model": "claude-haiku-5-5",
            "max_tokens": 200,
            "system": "Phân loại ticket vào: billing, bug, feature, other. Chỉ trả về nhãn.",
            "messages": [{"role": "user", "content": t["text"]}],
        },
    }
    for t in tickets
])
print(batch.id, batch.processing_status)  # in_progress

Lưu ý: tham số trong params được kiểm tra bất đồng bộ — lỗi chỉ hiện ra khi batch chạy xong. Vì vậy hãy gửi thử một request giống hệt qua Messages API thường trước khi đẩy cả lô.

Bước 2 — Theo dõi trạng thái

import time
while True:
    b = client.messages.batches.retrieve(batch.id)
    if b.processing_status == "ended":
        break
    print(b.request_counts)  # processing / succeeded / errored / canceled / expired
    time.sleep(60)

processing_status có 3 giá trị: in_progress, canceling, ended. Bạn cũng có thể xem trực tiếp trong Claude Console.

Bước 3 — Lấy kết quả

labels = {}
retry = []
for r in client.messages.batches.results(batch.id):
    match r.result.type:
        case "succeeded":
            labels[r.custom_id] = r.result.message.content[0].text
        case "errored":
            if r.result.error.error.type == "invalid_request_error":
                print("Sửa request:", r.custom_id)
            else:
                retry.append(r.custom_id)   # lỗi server: gửi lại được
        case "expired" | "canceled":
            retry.append(r.custom_id)

Kết quả là file .jsonl, mỗi dòng một object gồm custom_id và result. Quan trọng: thứ tự kết quả không khớp thứ tự gửi — luôn ghép bằng custom_id.

Bước 4 — Huỷ hoặc xoá khi cần

Gọi client.messages.batches.cancel(id) để huỷ batch đang chạy: trạng thái chuyển sang canceling rồi ended, có thể vẫn có kết quả một phần. Muốn xoá dữ liệu batch sau khi xử lý, dùng DELETE /v1/messages/batches/{batch_id} (batch đang chạy phải huỷ trước).

Kết hợp với prompt caching

Giảm giá batch và giảm giá cache cộng dồn. Vì các request trong batch chạy song song nên cache hit chỉ là “best-effort”, tỷ lệ thường từ 30% đến 98%. Để tăng tỷ lệ hit:

1. Đặt cùng một khối cache_control giống hệt nhau ở mọi request (ví dụ system prompt + tài liệu tham chiếu).
2. Gửi đều tay để cache (thời gian sống 5 phút) không hết hạn giữa chừng.
3. Thiết kế request để phần dùng chung càng lớn càng tốt; với batch chạy lâu, cân nhắc cache 1 giờ.

Khi nào dùng, khi nào không?

Lưu ý vận hành

• Chia nhỏ: dataset rất lớn nên tách thành nhiều batch để dễ theo dõi và retry.
• Stream kết quả: dùng iterator results() thay vì tải toàn bộ vào bộ nhớ.
• Spend limit: do throughput cao, batch có thể vượt nhẹ hạn mức chi tiêu của Workspace.
• Phạm vi Workspace: batch thuộc về Workspace tạo ra nó; chỉ API key cùng Workspace hoặc người có quyền trong Console mới xem được.
• Dữ liệu: request và response được lưu tối đa 29 ngày để xử lý; xoá chủ động bằng endpoint DELETE nếu dữ liệu nhạy cảm.

Áp dụng thế nào?

• Dev: Tách pipeline thành hai lớp — lớp real-time (API thường) cho người dùng, lớp batch chạy đêm cho phân tích, gắn nhãn, báo cáo. Hoá đơn giảm đáng kể mà trải nghiệm không đổi.
• Data/QA: Chạy bộ eval hàng nghìn case bằng batch mỗi khi đổi prompt — rẻ một nửa và không chiếm rate limit của API đồng bộ.
• PM: Khi ước tính chi phí AI cho tính năng, hỏi team: “phần nào chờ được vài giờ?”. Phần đó chuyển sang batch là tiết kiệm ngay 50%.