バッチ処理は、大量のリクエストを効率的に処理するための強力なアプローチです。リクエストを1つずつ処理して即座に応答する代わりに、バッチ処理では複数のリクエストをまとめて送信して非同期処理することができます。このパターンは特に以下の場合に有用です:
Message Batches APIは、Anthropicがこのパターンを実装した最初のものです。
This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.
Message Batches APIは、大量のMessagesリクエストを非同期で処理するための強力でコスト効率的な方法です。このアプローチは即座の応答を必要としないタスクに適しており、ほとんどのバッチは1時間以内に完了し、コストを50%削減しながらスループットを増加させます。
このガイドに加えて、APIリファレンスを直接確認することができます。
Message Batches APIにリクエストを送信する場合:
Was this page helpful?
これは、以下のような即座の結果を必要としないバルク操作に特に有用です:
すべてのアクティブなモデルがMessage Batches APIをサポートしています。
Messages APIに対して実行できるすべてのリクエストをバッチに含めることができます。これには以下が含まれます:
バッチ内の各リクエストは独立して処理されるため、単一のバッチ内で異なるタイプのリクエストを混在させることができます。
バッチは処理に5分以上かかる可能性があるため、バッチを共有コンテキストで処理する場合、プロンプトキャッシングでより高いキャッシュヒット率を得るために1時間のキャッシュ期間の使用を検討してください。
Batches APIは大幅なコスト削減を提供します。すべての使用は標準APIの50%の価格で請求されます。
| 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 | $0.50 / MTok | $2.50 / MTok |
| Claude Haiku 3.5 | $0.40 / MTok | $2 / MTok |
| Claude Opus 3 (deprecated) | $7.50 / MTok | $37.50 / MTok |
| Claude Haiku 3 | $0.125 / MTok | $0.625 / MTok |
Message Batchは、Messageを作成するためのリクエストのリストで構成されています。個別のリクエストの形状は以下で構成されています:
custom_idparamsオブジェクトこのリストをrequestsパラメータに渡すことで、バッチを作成できます:
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"}
]
}
}
]
}'この例では、2つの個別のリクエストが非同期処理のためにまとめてバッチ処理されています。各リクエストは一意の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に更新されます。Consoleにアクセスするか、取得エンドポイントを使用してバッチの状態を監視できます。
Message Batchをポーリングするには、バッチを作成するときの応答で提供される、またはバッチをリストすることで取得できるidが必要です。バッチのステータスを定期的にチェックするポーリングループを実装して、処理が終了するまで待機できます:
#!/bin/sh
until [[ $(curl -s "https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID" \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
| grep -o '"processing_status":[[:space:]]*"[^"]*"' \
| cut -d'"' -f4) == "ended" ]]; do
echo "Batch $MESSAGE_BATCH_ID is still processing..."
sleep 60
done
echo "Batch $MESSAGE_BATCH_ID has finished processing"リストエンドポイントを使用して、Workspace内のすべてのMessage Batchをリストできます。APIはページネーションをサポートし、必要に応じて自動的に追加ページを取得します:
#!/bin/sh
if ! command -v jq &> /dev/null; then
echo "Error: This script requires jq. Please install it first."
exit 1
fi
BASE_URL="https://api.anthropic.com/v1/messages/batches"
has_more=true
after_id=""
while [ "$has_more" = true ]; do
# Construct URL with after_id if it exists
if [ -n "$after_id" ]; then
url="${BASE_URL}?limit=20&after_id=${after_id}"
else
url="$BASE_URL?limit=20"
fi
response=$(curl -s "$url" \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01")
# Extract values using jq
has_more=$(echo "$response" | jq -r '.has_more')
after_id=$(echo "$response" | jq -r '.last_id')
# Process and print each entry in the data array
echo "$response" | jq -c '.data[]' | while read -r entry; do
echo "$entry" | jq '.'
done
doneバッチ処理が終了すると、バッチ内の各 Messages リクエストに結果があります。4 つの結果タイプがあります:
| 結果タイプ | 説明 |
|---|---|
succeeded | リクエストが成功しました。メッセージ結果が含まれます。 |
errored | リクエストがエラーに遭遇し、メッセージが作成されませんでした。考えられるエラーには、無効なリクエストと内部サーバーエラーが含まれます。これらのリクエストについては課金されません。 |
canceled | ユーザーがこのリクエストをモデルに送信する前にバッチをキャンセルしました。これらのリクエストについては課金されません。 |
expired | バッチがこのリクエストをモデルに送信する前に 24 時間の有効期限に達しました。これらのリクエストについては課金されません。 |
バッチの request_counts で結果の概要が表示され、これらの 4 つの状態に達したリクエストの数が示されます。
バッチの結果は、Message Batch の results_url プロパティでダウンロード可能であり、組織の権限が許可する場合は Console でも利用可能です。結果のサイズが大きい可能性があるため、すべてを一度にダウンロードするのではなく、結果をストリーミングすることをお勧めします。
#!/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_error" ]; 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
結果は .jsonl 形式で、各行は Message Batch 内の単一リクエストの結果を表す有効な JSON オブジェクトです。ストリーミングされた各結果に対して、その custom_id と結果タイプに応じて異なる処理を実行できます。以下は結果の例です:
{"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}}}}結果にエラーがある場合、その result.error は標準的なエラー形式に設定されます。
バッチ結果は入力順序と一致しない場合があります
バッチ結果は任意の順序で返される可能性があり、バッチが作成されたときのリクエストの順序と一致しない場合があります。上記の例では、2 番目のバッチリクエストの結果が最初のリクエストの前に返されています。結果を対応するリクエストと正しく照合するには、常に custom_id フィールドを使用してください。
キャンセルエンドポイントを使用して、現在処理中の Message Batch をキャンセルできます。キャンセル直後、バッチの processing_status は canceling になります。上記で説明したのと同じポーリング技術を使用して、キャンセルが完了するまで待機できます。キャンセルされたバッチは ended ステータスで終了し、キャンセル前に処理されたリクエストの部分的な結果が含まれる場合があります。
#!/bin/sh
curl --request POST https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/cancel \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01"レスポンスはバッチが canceling 状態であることを示します:
{
"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
}Message Batches API はプロンプトキャッシングをサポートしており、バッチリクエストのコストと処理時間を削減できる可能性があります。プロンプトキャッシングと Message Batches の価格割引は積み重ねることができ、両方の機能を一緒に使用すると、さらに大きなコスト削減が実現できます。ただし、バッチリクエストは非同期で同時に処理されるため、キャッシュヒットはベストエフォート方式で提供されます。ユーザーは通常、トラフィックパターンに応じて 30% から 98% のキャッシュヒット率を経験します。
バッチリクエストでキャッシュヒットの可能性を最大化するには:
cache_control ブロックを含めるバッチでプロンプトキャッシングを実装する例:
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."}
]
}
}
]
}'この例では、バッチ内の両方のリクエストに同一のシステムメッセージと Pride and Prejudice の全文が含まれており、cache_control でマークされてキャッシュヒットの可能性を高めています。
output-300k-2026-03-24 ベータヘッダーは、Claude Opus 4.6 または Claude Sonnet 4.6 を使用するバッチリクエストの max_tokens キャップを 300,000 に引き上げます。ヘッダーを含めることで、標準的な制限(モデルに応じて 64k から 128k)よりもはるかに長い出力を 1 回のターンで生成できます。
拡張出力は Message Batches API でのみ利用可能で、同期的な Messages API では利用できません。Claude API でサポートされており、Amazon Bedrock、Vertex AI、または Microsoft Foundry では利用できません。
拡張出力は、書籍の長さのドラフトと技術ドキュメント、徹底的な構造化データ抽出、大規模なコード生成スキャフォルド、長い推論チェーンなど、長文生成に使用します。
単一の 300k トークン生成は完了するのに 1 時間以上かかる可能性があるため、24 時間の処理ウィンドウを念頭に置いてバッチ送信を計画してください。標準的なバッチ価格(標準 API 価格の 50%)が適用されます。
curl https://api.anthropic.com/v1/messages/batches \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "anthropic-beta: output-300k-2026-03-24" \
--header "content-type: application/json" \
--data \
'{
"requests": [
{
"custom_id": "long-form-request",
"params": {
"model": "claude-opus-4-6",
"max_tokens": 300000,
"messages": [
{"role": "user", "content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices."}
]
}
}
]
}'Batches API を最大限に活用するには:
custom_id 値を使用する。順序は保証されないため予期しない動作が発生している場合:
request_too_large エラーが発生する可能性がありますcustom_id を持っていることを確認するcreated_at(処理 ended_at ではなく)時刻から 29 日未満であることを確認する。29 日以上経過している場合、結果は表示されなくなりますバッチ内の 1 つのリクエストの失敗は、他のリクエストの処理に影響しないことに注意してください。
ワークスペース分離: バッチは、作成されたワークスペース内で分離されます。そのワークスペースに関連付けられた API キー、またはコンソールでワークスペースバッチを表示する権限を持つユーザーのみがアクセスできます。
結果の可用性: バッチ結果は、バッチ作成後 29 日間利用可能で、取得と処理に十分な時間があります。
バッチ処理は、バッチ作成後最大 29 日間、リクエストとレスポンスデータを保存します。DELETE /v1/messages/batches/{batch_id} エンドポイントを使用して、処理後いつでもメッセージバッチを削除できます。進行中のバッチを削除するには、まずキャンセルしてください。非同期処理では、バッチ完了と結果取得まで、入力と出力の両方をサーバー側に保存する必要があります。
すべての機能にわたる ZDR 適格性については、API とデータ保持を参照してください。