バッチ処理は、大量のリクエストを効率的に処理するための強力なアプローチです。リクエストを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.7 | $2.50 / MTok | $12.50 / MTok |
| 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_id。1~64文字である必要があり、英数字、ハイフン、アンダースコアのみを含む必要があります(^[a-zA-Z0-9_-]{1,64}$に一致)。paramsオブジェクトこのリストをrequestsパラメータに渡すことでバッチを作成できます:
from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request
client = anthropic.Anthropic()
message_batch = client.messages.batches.create(
requests=[
Request(
custom_id="my-first-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-4-7",
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Hello, world",
}
],
),
),
Request(
custom_id="my-second-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-4-7",
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Hi again, friend",
}
],
),
),
]
)
print(message_batch)この例では、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が必要です。バッチのステータスを定期的にチェックするポーリングループを実装して、処理が終了するまで監視できます:
import time
client = anthropic.Anthropic()
MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"
message_batch = None
while True:
message_batch = client.messages.batches.retrieve(MESSAGE_BATCH_ID)
if message_batch.processing_status == "ended":
break
print(f"Batch {MESSAGE_BATCH_ID} is still processing...")
time.sleep(60)
print(message_batch)リストエンドポイントを使用してWorkspace内のすべてのMessage Batchをリストできます。APIはページネーションをサポートし、必要に応じて自動的に追加ページを取得します:
client = anthropic.Anthropic()
# Automatically fetches more pages as needed.
for message_batch in client.messages.batches.list(limit=20):
print(message_batch)バッチ処理が終了すると、バッチ内の各 Messages リクエストには結果があります。4 つの結果タイプがあります:
| 結果タイプ | 説明 |
|---|---|
succeeded | リクエストが成功しました。メッセージ結果が含まれます。 |
errored | リクエストがエラーに遭遇し、メッセージが作成されませんでした。考えられるエラーには、無効なリクエストと内部サーバーエラーが含まれます。これらのリクエストについては課金されません。 |
canceled | ユーザーがこのリクエストをモデルに送信する前にバッチをキャンセルしました。これらのリクエストについては課金されません。 |
expired | バッチがこのリクエストをモデルに送信する前に 24 時間の有効期限に達しました。これらのリクエストについては課金されません。 |
バッチの request_counts で結果の概要が表示され、これらの 4 つの状態に到達したリクエストの数が示されます。
バッチの結果は Message Batch の results_url プロパティでダウンロード可能であり、組織の権限が許可する場合は Console でも利用できます。結果のサイズが大きい可能性があるため、すべてを一度にダウンロードするのではなく、結果をストリーミングすることをお勧めします。
client = anthropic.Anthropic()
# Stream results file in memory-efficient chunks, processing one at a time
for result in client.messages.batches.results(
"msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
):
match result.result.type:
case "succeeded":
print(f"Success! {result.custom_id}")
case "errored":
if result.result.error.error.type == "invalid_request_error":
# Request body must be fixed before re-sending request
print(f"Validation error {result.custom_id}")
else:
# Request can be retried directly
print(f"Server error {result.custom_id}")
case "expired":
print(f"Request expired {result.custom_id}")結果は .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-7","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-7","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 ステータスで終了し、キャンセル前に処理されたリクエストの部分的な結果が含まれる場合があります。
client = anthropic.Anthropic()
MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"
message_batch = client.messages.batches.cancel(
MESSAGE_BATCH_ID,
)
print(message_batch)レスポンスはバッチが 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 ブロックを含めるバッチでプロンプトキャッシングを実装する例:
from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request
client = anthropic.Anthropic()
message_batch = client.messages.batches.create(
requests=[
Request(
custom_id="my-first-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-4-7",
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.",
}
],
),
),
Request(
custom_id="my-second-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-4-7",
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.",
}
],
),
),
]
)この例では、バッチ内の両方のリクエストに同一のシステムメッセージと、キャッシュヒットの可能性を高めるために cache_control でマークされた Pride and Prejudice の完全なテキストが含まれています。
output-300k-2026-03-24 ベータヘッダーは、Claude Opus 4.7、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%)が適用されます。
from anthropic.types.beta.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.beta.messages.batch_create_params import Request
client = anthropic.Anthropic()
message_batch = client.beta.messages.batches.create(
betas=["output-300k-2026-03-24"],
requests=[
Request(
custom_id="long-form-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-4-7",
max_tokens=300_000,
messages=[
{
"role": "user",
"content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices.",
}
],
),
),
],
)
print(message_batch)Batches API を最大限に活用するには:
custom_id 値を使用する(順序は保証されていないため)予期しない動作が発生している場合:
request_too_large エラーが発生する可能性がありますcustom_id を持っていることを確認するcreated_at(ended_at ではなく)時刻から 29 日未満であることを確認する。29 日以上経過している場合、結果は表示されなくなりますバッチ内の 1 つのリクエストの失敗は、他のリクエストの処理に影響しないことに注意してください。
ワークスペース分離:バッチは、それが作成されたワークスペース内に分離されます。それらは、そのワークスペースに関連付けられた API キー、または Console でワークスペースバッチを表示する権限を持つユーザーのみがアクセスできます。
結果の可用性:バッチ結果は、バッチが作成されてから 29 日間利用可能であり、取得と処理に十分な時間を提供します。
バッチ処理は、バッチ作成後最大 29 日間、リクエストとレスポンスデータを保存します。DELETE /v1/messages/batches/{batch_id} エンドポイントを使用して、処理後いつでもメッセージバッチを削除できます。進行中のバッチを削除するには、まずキャンセルしてください。非同期処理では、バッチ完了と結果取得までの間、入力と出力の両方をサーバー側に保存する必要があります。
すべての機能にわたる ZDR 適格性については、API とデータ保持を参照してください。