批次處理是一種高效處理大量請求的強大方法。與逐一處理請求並立即回應不同,批次處理允許您將多個請求一起提交進行非同步處理。這種模式在以下情況下特別有用:
Message Batches API 是我們對此模式的首次實作。
Message Batches API 是一種強大且具成本效益的方式,可非同步處理大量的 Messages 請求。這種方法非常適合不需要立即回應的任務,大多數批次在不到 1 小時內完成,同時降低 50% 的成本並提高吞吐量。
除了本指南外,您還可以直接探索 API 參考。
當您向 Message Batches API 發送請求時:
這對於不需要立即結果的批量操作特別有用,例如:
所有活躍模型都支援 Message Batches API。
任何您可以向 Messages API 發出的請求都可以包含在批次中。這包括:
由於批次中的每個請求都是獨立處理的,您可以在單個批次中混合不同類型的請求。
由於批次處理可能需要超過 5 分鐘,考慮在處理具有共享上下文的批次時使用1 小時快取持續時間與提示快取,以獲得更好的快取命中率。
Batches API 提供顯著的成本節省。所有使用量都以標準 API 價格的 50% 計費。
| Model | Batch input | Batch output |
|---|---|---|
| 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.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 | $0.50 / MTok | $2.50 / MTok |
| Claude Haiku 3.5 | $0.40 / MTok | $2 / MTok |
| Claude Opus 3 () |
Message Batch 由建立 Message 的請求清單組成。單個請求的結構包括:
custom_idparams 物件您可以透過將此清單傳遞到 requests 參數中來建立批次:
在此範例中,兩個獨立的請求被批次處理在一起進行非同步處理。每個請求都有一個唯一的 custom_id 並包含您用於 Messages API 呼叫的標準參數。
使用 Messages API 測試您的批次請求
每個訊息請求的 params 物件驗證是非同步執行的,驗證錯誤會在整個批次處理結束時返回。您可以透過首先使用 Messages API 驗證您的請求結構來確保您正確建構輸入。
當批次首次建立時,回應將具有 in_progress 的處理狀態。
{
"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
}Message Batch 的 processing_status 欄位指示批次處理所處的階段。它從 in_progress 開始,然後在批次中的所有請求完成處理且結果準備就緒後更新為 ended。您可以透過造訪控制台或使用檢索端點來監控批次的狀態:
您可以輪詢此端點以了解處理何時結束。
一旦批次處理結束,批次中的每個 Messages 請求都會有一個結果。有 4 種結果類型:
| 結果類型 | 描述 |
|---|---|
succeeded | 請求成功。包含訊息結果。 |
errored | 請求遇到錯誤且未建立訊息。可能的錯誤包括無效請求和內部伺服器錯誤。您不會為這些請求付費。 |
canceled | 使用者在此請求可以發送到模型之前取消了批次。您不會為這些請求付費。 |
expired | 批次在此請求可以發送到模型之前達到了 24 小時過期時間。您不會為這些請求付費。 |
您將透過批次的 request_counts 看到結果概覽,它顯示有多少請求達到了這四種狀態中的每一種。
批次的結果可在 Message Batch 的 results_url 屬性中下載,如果組織權限允許,也可在控制台中下載。由於結果的潛在大小,建議串流結果而不是一次下載所有結果。
結果將採用 .jsonl 格式,其中每行都是一個有效的 JSON 物件,代表 Message Batch 中單個請求的結果。對於每個串流結果,您可以根據其 custom_id 和結果類型執行不同的操作。以下是一組範例結果:
{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-sonnet-4-5-20250929","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-sonnet-4-5-20250929","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}}}}如果您的結果有錯誤,其 result.error 將設定為我們的標準錯誤結構。
批次結果可能不符合輸入順序
批次結果可以以任何順序返回,可能不符合建立批次時請求的順序。在上面的範例中,第二個批次請求的結果在第一個之前返回。要正確將結果與其對應的請求匹配,請始終使用 custom_id 欄位。
Message Batches API 支援提示快取,允許您可能降低批次請求的成本和處理時間。提示快取和 Message Batches 的定價折扣可以疊加,當兩個功能一起使用時提供更大的成本節省。但是,由於批次請求是非同步和並行處理的,快取命中是基於盡力而為的基礎提供的。使用者通常會體驗到 30% 到 98% 的快取命中率,這取決於他們的流量模式。
要最大化批次請求中快取命中的可能性:
cache_control 區塊在批次中實作提示快取的範例:
在此範例中,批次中的兩個請求都包含相同的系統訊息和標記為 cache_control 的《傲慢與偏見》全文,以增加快取命中的可能性。
要充分利用 Batches API:
custom_id 值以輕鬆將結果與請求匹配,因為順序不被保證。如果遇到意外行為:
request_too_large 錯誤。custom_id。created_at(不是處理 ended_at)時間起不到 29 天。如果超過 29 天,結果將不再可檢視。請注意,批次中一個請求的失敗不會影響其他請求的處理。
工作區隔離:批次在建立它們的工作區內被隔離。它們只能由與該工作區關聯的 API 金鑰或在控制台中有權限檢視工作區批次的使用者存取。
結果可用性:批次結果在批次建立後 29 天內可用,為檢索和處理提供充足的時間。
| $7.50 / MTok |
| $37.50 / MTok |
| Claude Haiku 3 | $0.125 / MTok | $0.625 / MTok |
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-sonnet-4-5",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hello, world"}
]
}
},
{
"custom_id": "my-second-request",
"params": {
"model": "claude-sonnet-4-5",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hi again, friend"}
]
}
}
]
}'curl https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
| sed -E 's/.*"id":"([^"]+)".*"processing_status":"([^"]+)".*/Batch \1 processing status is \2/'#!/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-sonnet-4-5",
"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-sonnet-4-5",
"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."}
]
}
}
]
}'