Loading...
  • ビルド
  • 管理
  • モデルと料金
  • クライアントSDK
  • APIリファレンス
Search...
⌘K
Log in
バッチ処理
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...

Solutions

  • AI agents
  • Code modernization
  • Coding
  • Customer support
  • Education
  • Financial services
  • Government
  • Life sciences

Partners

  • Amazon Bedrock
  • Google Cloud's Vertex AI

Learn

  • Blog
  • Courses
  • Use cases
  • Connectors
  • Customer stories
  • Engineering at Anthropic
  • Events
  • Powered by Claude
  • Service partners
  • Startups program

Company

  • Anthropic
  • Careers
  • Economic Futures
  • Research
  • News
  • Responsible Scaling Policy
  • Security and compliance
  • Transparency

Learn

  • Blog
  • Courses
  • Use cases
  • Connectors
  • Customer stories
  • Engineering at Anthropic
  • Events
  • Powered by Claude
  • Service partners
  • Startups program

Help and security

  • Availability
  • Status
  • Support
  • Discord

Terms and policies

  • Privacy policy
  • Responsible disclosure policy
  • Terms of service: Commercial
  • Terms of service: Consumer
  • Usage policy
ビルド/モデル機能

バッチ処理

大量のリクエストを効率的に処理するためのバッチ処理APIについて学びます

Was this page helpful?

  • Message Batches APIの仕組み
  • Message Batches APIの使用方法
  • すべてのMessage Batchをリストする
  • Message Batch のキャンセル
  • Message Batches でプロンプトキャッシングを使用する
  • FAQ

バッチ処理は、大量のリクエストを効率的に処理するための強力なアプローチです。リクエストを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

Message Batches APIは、Messagesリクエストの大量を非同期で処理するための強力でコスト効率的な方法です。このアプローチは即座の応答を必要としないタスクに適しており、ほとんどのバッチは1時間以内に完了し、コストを50%削減しながらスループットを増加させます。

このガイドに加えて、APIリファレンスを直接探索することができます。

Message Batches APIの仕組み

Message Batches APIにリクエストを送信すると:

  1. システムは提供されたMessagesリクエストで新しいMessage Batchを作成します。
  2. バッチは非同期で処理され、各リクエストは独立して処理されます。
  3. バッチのステータスをポーリングして、すべてのリクエストの処理が終了したときに結果を取得できます。

これは以下のような即座の結果を必要としないバルク操作に特に有用です:

  • 大規模な評価:数千のテストケースを効率的に処理します。
  • コンテンツモデレーション:ユーザー生成コンテンツの大量を非同期で分析します。
  • データ分析:大規模なデータセットに対する洞察または要約を生成します。
  • バルクコンテンツ生成:様々な目的(例:製品説明、記事の要約)のための大量のテキストを作成します。

バッチの制限

  • Message Batchは100,000のMessageリクエストまたは256 MBのサイズに制限されており、どちらかに先に達したものが適用されます。
  • システムは各バッチをできるだけ速く処理し、ほとんどのバッチは1時間以内に完了します。すべてのメッセージが完了したとき、または24時間後のいずれか早い方でバッチ結果にアクセスできます。処理が24時間以内に完了しない場合、バッチは期限切れになります。
  • バッチ結果は作成後29日間利用可能です。その後、バッチを表示することはできますが、その結果はダウンロードできなくなります。
  • バッチはWorkspaceにスコープされます。APIキーが属するWorkspace内で作成されたすべてのバッチ(およびその結果)を表示できます。
  • レート制限は、Batches API HTTPリクエストと、処理待ちのバッチ内のリクエスト数の両方に適用されます。Message Batches APIレート制限を参照してください。さらに、現在の需要とリクエストボリュームに基づいて処理が遅くなる可能性があります。その場合、24時間後に期限切れになるリクエストが増える可能性があります。
  • 高いスループットと並行処理により、バッチはWorkspaceの設定された支出制限をわずかに超える可能性があります。

サポートされているモデル

すべてのアクティブなモデルがMessage Batches APIをサポートしています。

バッチ処理できるもの

Messages APIに対して実行できるすべてのリクエストをバッチに含めることができます。これには以下が含まれます:

  • Vision
  • ツール使用
  • システムメッセージ
  • マルチターン会話
  • すべてのベータ機能

バッチ内の各リクエストは独立して処理されるため、単一のバッチ内で異なるタイプのリクエストを混在させることができます。

バッチは処理に5分以上かかる可能性があるため、バッチ処理時に共有コンテキストでより高いキャッシュヒット率を得るために、プロンプトキャッシングで1時間のキャッシュ期間を使用することを検討してください。


価格

Batches APIは大幅なコスト削減を提供します。すべての使用は標準APIの価格の50%で請求されます。

ModelBatch inputBatch 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)

Message Batches APIの使用方法

バッチを準備して作成する

Message Batchは、Messageを作成するためのリクエストのリストで構成されています。個別のリクエストの形状は以下で構成されています:

  • Messagesリクエストを識別するための一意のcustom_id。1~64文字である必要があり、英数字、ハイフン、アンダースコアのみを含む必要があります(^[a-zA-Z0-9_-]{1,64}$に一致)。
  • 標準的なMessages APIパラメータを含むparamsオブジェクト

このリストをrequestsパラメータに渡すことでバッチを作成できます:

この例では、2つの個別のリクエストが非同期処理のためにまとめてバッチ処理されています。各リクエストは一意のcustom_idを持ち、Messages APIコールに使用する標準パラメータを含んでいます。

Messages APIでバッチリクエストをテストする

各メッセージリクエストのparamsオブジェクトの検証は非同期で実行され、バッチ全体の処理が終了したときに検証エラーが返されます。Messages APIでリクエスト形状を最初に検証することで、入力を正しく構築していることを確認できます。

バッチが最初に作成されると、応答はin_progressの処理ステータスを持ちます。

Output
{
  "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の完了をポーリングする

Message Batchをポーリングするには、バッチ作成時の応答で提供される、またはバッチをリストすることで取得できるidが必要です。バッチのステータスを定期的にチェックするポーリングループを実装して、処理が終了するまで監視できます:

すべてのMessage Batchをリストする

リストエンドポイントを使用してWorkspace内のすべてのMessage Batchをリストできます。APIはページネーションをサポートし、必要に応じて自動的に追加ページを取得します:

バッチ結果の取得

バッチ処理が終了すると、バッチ内の各 Messages リクエストには結果があります。4 つの結果タイプがあります:

結果タイプ説明
succeededリクエストが成功しました。メッセージ結果が含まれます。
erroredリクエストがエラーに遭遇し、メッセージが作成されませんでした。考えられるエラーには、無効なリクエストと内部サーバーエラーが含まれます。これらのリクエストについては課金されません。
canceledユーザーがこのリクエストをモデルに送信する前にバッチをキャンセルしました。これらのリクエストについては課金されません。
expiredバッチがこのリクエストをモデルに送信する前に 24 時間の有効期限に達しました。これらのリクエストについては課金されません。

バッチの request_counts で結果の概要が表示され、これらの 4 つの状態に到達したリクエストの数が示されます。

バッチの結果は Message Batch の results_url プロパティでダウンロード可能であり、組織の権限が許可する場合は Console でも利用できます。結果のサイズが大きい可能性があるため、すべてを一度にダウンロードするのではなく、結果をストリーミングすることをお勧めします。

結果は .jsonl 形式で、各行は Message Batch 内の単一リクエストの結果を表す有効な JSON オブジェクトです。ストリーミングされた各結果について、その custom_id と結果タイプに応じて異なる処理を実行できます。以下は結果の例です:

.jsonl file
{"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 のキャンセル

キャンセルエンドポイントを使用して、現在処理中の Message Batch をキャンセルできます。キャンセル直後、バッチの processing_status は canceling になります。上記で説明したのと同じポーリング技術を使用して、キャンセルが完了するまで待つことができます。キャンセルされたバッチは ended ステータスで終了し、キャンセル前に処理されたリクエストの部分的な結果が含まれる場合があります。

レスポンスはバッチが canceling 状態であることを示します:

Output
{
  "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 でプロンプトキャッシングを使用する

Message Batches API はプロンプトキャッシングをサポートしており、バッチリクエストのコストと処理時間を削減できる可能性があります。プロンプトキャッシングと Message Batches の価格割引は重ねることができ、両方の機能を一緒に使用すると、さらに大きなコスト削減が実現します。ただし、バッチリクエストは非同期で同時に処理されるため、キャッシュヒットはベストエフォート基準で提供されます。ユーザーは通常、トラフィックパターンに応じて 30% から 98% のキャッシュヒット率を経験します。

バッチリクエストでキャッシュヒットの可能性を最大化するには:

  1. バッチ内のすべての Message リクエストに同一の cache_control ブロックを含める
  2. キャッシュエントリが 5 分のライフタイム後に期限切れになるのを防ぐため、リクエストの安定したストリームを維持する
  3. できるだけ多くのキャッシュされたコンテンツを共有するようにリクエストを構造化する

バッチでプロンプトキャッシングを実装する例:

この例では、バッチ内の両方のリクエストに同一のシステムメッセージと、キャッシュヒットの可能性を高めるために 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%)が適用されます。

効果的なバッチ処理のベストプラクティス

Batches API を最大限に活用するには:

  • バッチ処理ステータスを定期的に監視し、失敗したリクエストに対して適切なリトライロジックを実装する
  • 結果とリクエストを簡単に照合できるように、意味のある custom_id 値を使用する(順序は保証されていないため)
  • 非常に大きなデータセットを複数のバッチに分割して、管理性を向上させることを検討する
  • Messages API で単一のリクエスト形状をドライラン実行して、検証エラーを回避する

一般的な問題のトラブルシューティング

予期しない動作が発生している場合:

  • バッチリクエストの合計サイズが 256 MB を超えていないことを確認する。リクエストサイズが大きすぎる場合、413 request_too_large エラーが発生する可能性があります
  • バッチ内のすべてのリクエストでサポートされているモデルを使用していることを確認する
  • バッチ内の各リクエストが一意の custom_id を持っていることを確認する
  • バッチ created_at(ended_at ではなく)時刻から 29 日未満であることを確認する。29 日以上経過している場合、結果は表示されなくなります
  • バッチがキャンセルされていないことを確認する

バッチ内の 1 つのリクエストの失敗は、他のリクエストの処理に影響しないことに注意してください。


バッチストレージとプライバシー

  • ワークスペース分離:バッチは、それが作成されたワークスペース内に分離されます。それらは、そのワークスペースに関連付けられた API キー、または Console でワークスペースバッチを表示する権限を持つユーザーのみがアクセスできます。

  • 結果の可用性:バッチ結果は、バッチが作成されてから 29 日間利用可能であり、取得と処理に十分な時間を提供します。


データ保持

バッチ処理は、バッチ作成後最大 29 日間、リクエストとレスポンスデータを保存します。DELETE /v1/messages/batches/{batch_id} エンドポイントを使用して、処理後いつでもメッセージバッチを削除できます。進行中のバッチを削除するには、まずキャンセルしてください。非同期処理では、バッチ完了と結果取得までの間、入力と出力の両方をサーバー側に保存する必要があります。

すべての機能にわたる ZDR 適格性については、API とデータ保持を参照してください。

FAQ

$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
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)
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)
client = anthropic.Anthropic()

# Automatically fetches more pages as needed.
for message_batch in client.messages.batches.list(limit=20):
    print(message_batch)
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}")
client = anthropic.Anthropic()

MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"

message_batch = client.messages.batches.cancel(
    MESSAGE_BATCH_ID,
)
print(message_batch)
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.",
                    }
                ],
            ),
        ),
    ]
)
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)