バッチ処理は、大量のリクエストを効率的に処理するための強力なアプローチです。即座にレスポンスを返すリクエストを一つずつ処理する代わりに、バッチ処理では複数のリクエストをまとめて送信し、非同期で処理することができます。このパターンは特に以下の場合に有用です：
  • 大量のデータを処理する必要がある場合
  • 即座のレスポンスが不要な場合
  • コスト効率を最適化したい場合
  • 大規模な評価や分析を実行している場合
Message Batches APIは、このパターンの最初の実装です。

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

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

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

​
バッチ処理できるもの

Messages APIに対して行えるあらゆるリクエストをバッチに含めることができます。これには以下が含まれます：
  • ビジョン
  • ツール使用
  • システムメッセージ
  • マルチターン会話
  • あらゆるベータ機能
バッチ内の各リクエストは独立して処理されるため、単一のバッチ内で異なるタイプのリクエストを混在させることができます。
バッチの処理には5分以上かかる場合があるため、共有コンテキストでバッチを処理する際のキャッシュヒット率を向上させるために、プロンプトキャッシュで1時間のキャッシュ期間の使用を検討してください。

​
価格設定

Batches APIは大幅なコスト削減を提供します。すべての使用量は標準API価格の50%で課金されます。
ModelBatch inputBatch output
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$1.50 / MTok$7.50 / MTok
Claude Sonnet 3.5 (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 Batches APIの使用方法

​
バッチの準備と作成

Message Batchは、Messageを作成するリクエストのリストで構成されます。個々のリクエストの形状は以下で構成されます：
  • Messagesリクエストを識別するための一意のcustom_id
  • 標準のMessages APIパラメータを含むparamsオブジェクト
このリストを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-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"}
                ]
            }
        }
    ]
}'
この例では、2つの別々のリクエストが非同期処理のためにまとめてバッチ化されています。各リクエストには一意のcustom_idがあり、Messages API呼び出しで使用する標準パラメータが含まれています。
Messages APIでバッチリクエストをテストする各メッセージリクエストのparamsオブジェクトの検証は非同期で実行され、バッチ全体の処理が終了したときに検証エラーが返されます。まずMessages APIでリクエストの形状を確認することで、入力を正しく構築していることを確認できます。
バッチが最初に作成されたとき、レスポンスの処理ステータスはin_progressになります。
JSON
{
  "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に更新されます。コンソールにアクセスするか、取得エンドポイントを使用してバッチの状態を監視できます： 
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/'
このエンドポイントをポーリングして、処理が終了したことを知ることができます。

​
バッチ結果の取得

バッチ処理が終了すると、バッチ内の各Messagesリクエストに結果が生成されます。結果タイプは4つあります：
結果タイプ説明
succeededリクエストが成功しました。メッセージ結果が含まれます。
erroredリクエストでエラーが発生し、メッセージが作成されませんでした。無効なリクエストや内部サーバーエラーなどが考えられます。これらのリクエストに対しては課金されません。
canceledこのリクエストがモデルに送信される前に、ユーザーがバッチをキャンセルしました。これらのリクエストに対しては課金されません。
expiredこのリクエストがモデルに送信される前に、バッチが24時間の期限に達しました。これらのリクエストに対しては課金されません。
バッチのrequest_countsで結果の概要を確認できます。これは、これら4つの状態のそれぞれに達したリクエストの数を示します。 バッチの結果は、Message Batchのresults_urlプロパティでダウンロード可能で、組織の権限が許可している場合はコンソールでも利用できます。結果のサイズが大きくなる可能性があるため、すべてを一度にダウンロードするのではなく、結果をストリーミングすることをお勧めします。 
#!/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
結果は.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-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は標準のエラー形状に設定されます。
バッチ結果は入力順序と一致しない場合がありますバッチ結果は任意の順序で返される可能性があり、バッチが作成されたときのリクエストの順序と一致しない場合があります。上記の例では、2番目のバッチリクエストの結果が最初のものより前に返されています。結果を対応するリクエストと正しく照合するには、常にcustom_idフィールドを使用してください。

​
Message Batchesでのプロンプトキャッシュの使用

Message Batches APIはプロンプトキャッシュをサポートしており、バッチリクエストのコストと処理時間を削減できる可能性があります。プロンプトキャッシュとMessage Batchesの価格割引は重複適用でき、両方の機能を一緒に使用することでさらに大きなコスト削減を実現できます。ただし、バッチリクエストは非同期かつ並行して処理されるため、キャッシュヒットはベストエフォートベースで提供されます。ユーザーは通常、トラフィックパターンに応じて30%から98%のキャッシュヒット率を経験します。 バッチリクエストでキャッシュヒットの可能性を最大化するには：
  1. バッチ内のすべてのMessageリクエストに同一のcache_controlブロックを含める
  2. キャッシュエントリが5分の有効期間後に期限切れになることを防ぐため、リクエストの安定したストリームを維持する
  3. 可能な限り多くのキャッシュされたコンテンツを共有するようにリクエストを構造化する
バッチでプロンプトキャッシュを実装する例： 
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."}
                ]
            }
        }
    ]
}'
この例では、バッチ内の両方のリクエストに、キャッシュヒットの可能性を高めるためにcache_controlでマークされた同一のシステムメッセージと『高慢と偏見』の全文が含まれています。

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

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

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

予期しない動作が発生した場合：
  • バッチリクエストの総サイズが256MBを超えていないことを確認する。リクエストサイズが大きすぎる場合、413 request_too_largeエラーが発生する可能性があります。
  • バッチ内のすべてのリクエストでサポートされているモデルを使用していることを確認する。
  • バッチ内の各リクエストが一意のcustom_idを持っていることを確認する。
  • バッチのcreated_at時刻（処理ended_at時刻ではない）から29日未満であることを確認する。29日を超えた場合、結果は表示できなくなります。
  • バッチがキャンセルされていないことを確認する。
バッチ内の1つのリクエストの失敗は、他のリクエストの処理に影響しないことに注意してください。

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

  • ワークスペースの分離：バッチは作成されたワークスペース内で分離されます。そのワークスペースに関連付けられたAPIキー、またはコンソールでワークスペースバッチを表示する権限を持つユーザーのみがアクセスできます。
  • 結果の可用性：バッチ結果はバッチ作成から29日間利用可能で、取得と処理に十分な時間を提供します。

​
FAQ

バッチの処理には最大24時間かかる場合がありますが、多くはより早く完了します。実際の処理時間は、バッチのサイズ、現在の需要、およびリクエスト量によって異なります。バッチが期限切れになり、24時間以内に完了しない可能性があります。
サポートされているモデルのリストについては、上記を参照してください。
はい、Message Batches APIはベータ機能を含むMessages APIで利用可能なすべての機能をサポートしています。ただし、バッチリクエストではストリーミングはサポートされていません。
Message Batches APIは、標準API価格と比較してすべての使用量で50%の割引を提供します。これは入力トークン、出力トークン、および特別なトークンに適用されます。価格設定の詳細については、価格設定ページをご覧ください。
いいえ、バッチが送信された後は変更できません。変更が必要な場合は、現在のバッチをキャンセルして新しいものを送信する必要があります。キャンセルは即座に効果を発揮しない場合があることに注意してください。
Message Batches APIには、処理が必要なリクエスト数の制限に加えて、HTTPリクエストベースのレート制限があります。Message Batches APIレート制限を参照してください。Batches APIの使用は、Messages APIのレート制限に影響しません。
結果を取得する際、各リクエストにはsucceeded、errored、canceled、またはexpiredを示すresultフィールドがあります。errored結果の場合、追加のエラー情報が提供されます。APIリファレンスでエラーレスポンスオブジェクトを確認してください。
Message Batches APIは強力なプライバシーとデータ分離対策で設計されています：
  1. バッチとその結果は、作成されたワークスペース内で分離されます。つまり、同じワークスペースのAPIキーのみがアクセスできます。
  2. バッチ内の各リクエストは独立して処理され、リクエスト間でのデータ漏洩はありません。
  3. 結果は限られた時間（29日間）のみ利用可能で、データ保持ポリシーに従います。
  4. コンソールでのバッチ結果のダウンロードは、組織レベルまたはワークスペースごとに無効にできます。
はい、Message Batches APIでプロンプトキャッシュを使用することは可能です。ただし、非同期バッチリクエストは並行して任意の順序で処理される可能性があるため、キャッシュヒットはベストエフォートベースで提供されます。