Trả lời nhanh: Claude Batch API xử lý các yêu cầu Messages API theo cách bất đồng bộ với mức giảm 50% cho cả token đầu vào và đầu ra. Bạn gửi tối đa 100.000 yêu cầu (hoặc 256 MB) trong một lần gọi, thăm dò cho đến khi lô kết thúc, rồi đọc kết quả được đánh khóa theo custom_id của chính bạn. Hầu hết các lô hoàn thành trong vòng một giờ, và giới hạn cứng là 24 giờ.
Bạn có 40.000 phiếu hỗ trợ cần phân loại, hoặc một danh mục sản phẩm cần viết lại, hoặc một tháng bản ghi cần tóm tắt. Không việc nào gấp cả. Mỗi lần gọi đó vẫn bị tính phí đầy đủ khi bạn gửi từng cái một, và bạn mất cả buổi chiều để trông chừng việc thử lại do vượt giới hạn tốc độ.
Claude Batch API ra đời chính xác cho dạng công việc này. Bạn đưa cho Anthropic một danh sách yêu cầu, rồi rời đi, và quay lại với một tệp kết quả có chi phí chỉ bằng một nửa so với việc gọi đồng bộ cùng những lệnh đó. Không cần chạy hàng đợi, không cần tinh chỉnh đồng thời, không cần logic backoff.
Hướng dẫn này trình bày điểm cuối batch làm gì, chi phí ra sao, cách gửi và thu thập một tác vụ, và cách để tác nhân lập trình của bạn kiểm thử toàn bộ quy trình với Apidog CLI trước khi bạn hướng nó vào dữ liệu thật.
Claude Batch API là gì?
Claude Batch API là một điểm cuối bất đồng bộ tại /v1/messages/batches, tiếp nhận nhiều yêu cầu Messages API trong một lần gửi duy nhất và trả về kết quả của chúng khi quá trình xử lý kết thúc. Nó đánh đổi độ trễ để lấy mức giảm 50%. Anthropic tài liệu hóa nó trong phần batch processing.
Những ràng buộc bạn cần thiết kế xoay quanh:
- Kích thước: tối đa 100.000 yêu cầu hoặc 256 MB mỗi lô, tùy cái nào đạt trước.
- Thời gian: hầu hết các lô hoàn thành trong vòng một giờ; 24 giờ là mức tối đa trước khi các yêu cầu chưa hoàn tất hết hạn.
- Thời gian lưu trữ: kết quả vẫn khả dụng trong 29 ngày sau khi lô được tạo.
- Tính năng tương đương: thị giác, sử dụng công cụ, lời nhắc hệ thống và bộ nhớ đệm lời nhắc đều hoạt động trong một lô.
- Thứ tự: kết quả trả về theo bất kỳ thứ tự nào, vì vậy bạn đánh khóa chúng theo
custom_idchứ không bao giờ theo vị trí.
Điểm cuối cùng đó chính là thứ khiến người ta dễ vấp. Một lô là một cái túi, không phải một hàng đợi.
Claude Batch API tốn bao nhiêu?
Mức giảm là phẳng 50% cho cả token đầu vào và đầu ra, áp dụng cho bất kỳ mô hình nào mà mỗi yêu cầu chỉ định. Bạn có thể trộn nhiều mô hình trong một lô, nên một bộ phân loại rẻ tiền và một bộ tóm tắt đắt tiền có thể đi cùng nhau.
| Mô hình | Đầu vào / đầu ra tiêu chuẩn mỗi MTok | Đầu vào / đầu ra theo lô mỗi 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 (lời nhắc tối đa 100K) | $0.10 / $0.50 | $0.05 / $0.25 |
| Claude Haiku 5.5 (lời nhắc trên 100K) | $0.50 / $2.50 | $0.25 / $1.25 |
Hãy đọc kỹ các hàng Haiku. Haiku 5.5 tính giá theo kích thước lời nhắc, nên một lời nhắc vượt qua 100.000 token sẽ bị tính gấp 5 lần mức giá lời nhắc ngắn, bất kể có giảm giá theo lô hay không. Hãy dự phóng công việc Haiku với ngữ cảnh dài ở mức $0.25 / $1.25, chứ không phải $0.05 / $0.25. Hãy kiểm tra trang giá của Anthropic trước khi bạn xây dựng dự phóng dựa trên những con số này, và đọc bài phân tích của chúng tôi về chi phí Claude API đi về đâu nếu hóa đơn là lý do bạn đến đây.
Giá theo lô cũng cộng dồn với bộ nhớ đệm lời nhắc, đó chính là nơi khoản tiết kiệm thật sự nằm. Sẽ nói thêm ở dưới.
Gửi lô đầu tiên của bạn
Cài đặt SDK Python chính thức và xây dựng một danh sách yêu cầu. Mỗi yêu cầu mang một custom_id do bạn chọn và một đối tượng params trông y hệt một lệnh gọi messages.create() bình thường.
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)
Hãy làm cho custom_id mang ý nghĩa. Một khóa chính trong cơ sở dữ liệu hoặc một đường dẫn tệp sẽ giúp bạn khỏi phải ghép nối về sau, và đó là thứ duy nhất gắn một kết quả trở lại đầu vào của nó.
Nếu bạn thích HTTP thuần, cùng một payload đó được gửi đến POST https://api.anthropic.com/v1/messages/batches với các header x-api-key và anthropic-version của bạn. Tài liệu tham chiếu create a message batch có đầy đủ lược đồ.
Thăm dò lô và thu thập kết quả
Truy xuất lô cho đến khi processing_status hiển thị ended, rồi truyền phát kết quả. Mỗi kết quả mang custom_id bạn đã đặt và một result.type là succeeded, errored, canceled, hoặc 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")
Hai dạng lỗi cần được xử lý riêng. Lỗi invalid_request nghĩa là phần thân yêu cầu bị sai, nên hãy sửa nó trước khi gửi lại. Mọi thứ khác đều thuộc phía máy chủ và an toàn để thử lại nguyên trạng. Kết quả expired nghĩa là cửa sổ 24 giờ đã đóng trước khi yêu cầu đó chạy, và bạn cũng gửi lại những cái đó.
Hãy thăm dò theo nhịp 30 đến 60 giây. Việc dội liên tục vào điểm cuối retrieve mỗi giây chẳng mang lại gì cho bạn và còn bị tính vào giới hạn tốc độ Claude API của bạn.
Cộng dồn giá theo lô với bộ nhớ đệm lời nhắc
Lợi ích lớn nhất đến từ việc kết hợp hai khoản giảm giá. Nếu mọi yêu cầu trong lô của bạn chia sẻ một tiền tố dài, một hướng dẫn văn phong, một hệ phân loại, một hợp đồng 40 trang, hãy đánh dấu tiền tố đó bằng cache_control và gửi cùng tiền tố đã đánh dấu đó trên cả 10.000 yêu cầu.
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"},
},
]
Hãy đặt khối system đó trên mọi Request trong lô. Bất kỳ yêu cầu nào có tiền tố khớp từng byte với một mục bộ nhớ đệm còn hiệu lực sẽ được tính tiền tố đó theo mức giá đọc bộ nhớ đệm, và mức giảm 50% theo lô áp dụng cho cả việc đọc lẫn ghi bộ nhớ đệm. Đừng dự trù cho tỷ lệ trúng hoàn hảo: một lô xử lý các yêu cầu của nó đồng thời thay vì theo thứ tự, nên việc trúng bộ nhớ đệm trong một lô chỉ ở mức cố gắng tốt nhất. Hướng dẫn bộ nhớ đệm lời nhắc của Anthropic trình bày các quy tắc tiền tố: bất kỳ byte nào thay đổi trước điểm ngắt của bạn đều vô hiệu hóa mọi thứ sau nó, vì vậy hãy giữ dấu thời gian và văn bản theo từng mục ở phía sau khối được đệm.
Để Claude Code kiểm thử điểm cuối với Apidog CLI
Trước khi bạn tiêu tiền cho 100.000 yêu cầu thật, bạn muốn có một bài kiểm thử hồi quy trên vòng đời của lô: tạo, truy xuất, kết quả. Viết thủ công việc đó trong một GUI thì chậm. Hãy để tác nhân lập trình của bạn làm điều đó với Apidog CLI.
npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install # pick Claude Code when prompted
Rồi một lời nhắc cho 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.
Tác nhân đọc lược đồ payload, tự xác thực JSON của nó, rồi tạo và chạy ca kiểm thử:
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
Khóa API của bạn nằm trong một biến môi trường của Apidog, nên nó không bao giờ lọt vào lời nhắc hay kho mã. Đổi trình báo cáo sang -r junit và cùng lệnh đó sẽ chạy trong CI ở mỗi lần hợp nhất, đây chính là thiết lập trong hướng dẫn pipeline Apidog CLI của chúng tôi. Nếu bạn chưa nối CLI vào tác nhân của mình, hãy bắt đầu với dùng Apidog CLI trong Claude Code.
Khi nào batch là lựa chọn sai
| Khối lượng công việc | Dùng batch? | Lý do |
|---|---|---|
| Tóm tắt nhật ký của ngày hôm qua vào ban đêm | Có | Không ai đang chờ; giảm 50% |
| Bổ sung embeddings hoặc nhãn cho một kho ngữ liệu | Có | Vừa với giới hạn 100.000 yêu cầu |
| Chạy đánh giá trên một bộ lời nhắc | Có | Kết quả đánh khóa theo custom_id ánh xạ tới ID kiểm thử |
| Phản hồi trên giao diện chat | Không | Người dùng sẽ không chờ một giờ |
| Vòng lặp tác nhân cần câu trả lời cuối để chọn bước tiếp theo | Không | Các yêu cầu trong lô không thể nhìn thấy nhau |
| Một yêu cầu phải đạt SLA 5 giây | Không | Không có bảo đảm độ trễ dưới 24 giờ |
Một vài thứ cũng không vượt qua được. Chế độ nhanh không khả dụng trên Batch API, các cơ chế dự phòng từ chối phía máy chủ bị từ chối ở đó, và trên Claude Opus 5.5 và Claude Sonnet 5.5, việc ép buộc tool_choice là any hoặc tool sẽ trả về lỗi 400 bên trong một lô y hệt như khi gọi bình thường. Thay vào đó hãy dùng tool_choice: auto với strict: true.
Nếu bạn vận hành hạ tầng đa nhà cung cấp, mô hình tương tự cũng tồn tại ở nơi khác: xem OpenAI Batch API và chế độ batch của Gemini API. Hình dạng khác nhau, nhưng kinh tế thì không.
Câu hỏi thường gặp
Claude Batch API là gì?
Đó là một điểm cuối bất đồng bộ chạy các yêu cầu Messages API tiêu chuẩn theo lô lớn với mức 50% giá token thông thường. Bạn gửi một danh sách yêu cầu kèm ID của riêng bạn, thăm dò cho đến khi lô kết thúc, và đọc kết quả trong vòng 29 ngày.
Claude Batch API tốn bao nhiêu?
Bằng một nửa mức giá tiêu chuẩn cho cả đầu vào và đầu ra. Trên Claude Sonnet 5.5, đó là $1.00 mỗi triệu token đầu vào và $5.00 mỗi triệu token đầu ra, so với $2.00 và $10.00 khi đồng bộ.
Một lô Claude mất bao lâu?
Hầu hết các lô hoàn thành trong vòng một giờ. Mức tối đa là 24 giờ, sau đó bất kỳ yêu cầu nào chưa được xử lý sẽ trả về kết quả expired và bạn gửi lại nó.
Tôi có thể dùng bộ nhớ đệm lời nhắc bên trong một lô không?
Có, và các khoản giảm giá cộng dồn. Hãy đánh dấu một tiền tố chia sẻ bằng cache_control, lặp lại tiền tố y hệt đó trên mọi yêu cầu, và các lần đọc được đệm sẽ được tính ở một phần nhỏ giá đầu vào, cộng thêm mức giảm theo lô.
Điều gì xảy ra khi một yêu cầu trong lô thất bại?
Chỉ yêu cầu đó thất bại. Kết quả của nó mang type: "errored" kèm một đối tượng lỗi; mọi thứ còn lại vẫn thành công. Lỗi xác thực cần một payload đã sửa, lỗi máy chủ thì an toàn để thử lại nguyên trạng.
Tôi có thể hủy một lô đang chạy không?
Có. client.messages.batches.cancel(batch_id) chuyển lô sang trạng thái canceling. Các yêu cầu đã hoàn tất giữ nguyên kết quả; phần còn lại trả về là canceled.
Batch API có hỗ trợ công cụ và hình ảnh không?
Có. Mọi tính năng của Messages API đều hoạt động bên trong một lô, bao gồm thị giác, định nghĩa công cụ và lời nhắc hệ thống. Các ngoại lệ là chế độ nhanh, dự phòng phía máy chủ, và ép buộc chọn công cụ trên các mô hình 5.5.
Tổng kết
Xử lý theo lô là khoản tiết kiệm miễn phí lớn thứ hai trên Claude API sau bộ nhớ đệm lời nhắc, và nó chẳng khiến bạn mất gì về chất lượng: cùng mô hình, cùng tính năng, một nửa giá, đổi lại bằng độ trễ mà có lẽ bạn vốn không dùng đến. Hãy đánh khóa kết quả theo custom_id, đệm tiền tố chia sẻ, và xử lý expired như một lần thử lại chứ không phải một thất bại.
Hãy kiểm thử vòng đời trước khi bạn mở rộng quy mô. Cài đặt Apidog CLI, hướng tác nhân lập trình của bạn vào các điểm cuối batch, và giữ ca kiểm thử được tạo chạy trong CI để một thay đổi lược đồ không bao giờ làm bạn bất ngờ ở mốc 100.000 yêu cầu. Gói miễn phí bao gồm 4 người dùng, và bạn có thể tải Apidog và có ca kiểm thử đầu tiên chạy trong vài phút.