機能

バッチ処理

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

バッチ処理は、大量のリクエストを効率的に処理するための強力なアプローチです。リクエストを1つずつ処理して即座に応答する代わりに、バッチ処理では複数のリクエストをまとめて送信して非同期処理することができます。このパターンは特に以下の場合に有用です：

大量のデータを処理する必要がある
即座の応答が不要である
コスト効率を最適化したい
大規模な評価または分析を実行している

Message Batches APIは、このパターンの最初の実装です。

Message Batches API

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

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

Message Batches APIの仕組み

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

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

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

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

バッチの制限

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
Tool use
システムメッセージ
マルチターン会話
すべてのベータ機能

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

バッチは処理に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 (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に更新されます。Consoleにアクセスするか、取得エンドポイントを使用してバッチの状態を監視できます。

Message Batchの完了をポーリングする

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

import anthropic
import time

client = anthropic.Anthropic()

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)

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

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

import anthropic

client = anthropic.Anthropic()

# 必要に応じて自動的により多くのページを取得します。
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でも利用可能です。結果の潜在的に大きなサイズのため、すべてを一度にダウンロードするのではなく、結果をストリーミングすることをお勧めします。

#!/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
            # リクエスト本体は再送信前に修正する必要があります
            echo "Validation error: $custom_id"
          else
            # リクエストは直接再試行できます
            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 Batchのキャンセル

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

import anthropic

client = anthropic.Anthropic()

message_batch = client.messages.batches.cancel(
    MESSAGE_BATCH_ID,
)
print(message_batch)

応答はバッチをcanceling状態で表示します：

JSON

{
  "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% のキャッシュヒット率を経験します。

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

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

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

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 でマークされた Pride and Prejudice の完全なテキストが含まれています。

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

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

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

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

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

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

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

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

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

FAQ

機能

バッチ処理

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

大量のデータを処理する必要がある
即座の応答が不要である
コスト効率を最適化したい
大規模な評価または分析を実行している

Message Batches APIは、このパターンの最初の実装です。

Message Batches API

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

Message Batches APIの仕組み

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

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

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

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

バッチの制限

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
Tool use
システムメッセージ
マルチターン会話
すべてのベータ機能

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

価格設定

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 (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"}
                ]
            }
        }
    ]
}'

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

import anthropic
import time

client = anthropic.Anthropic()

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)

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

import anthropic

client = anthropic.Anthropic()

# 必要に応じて自動的により多くのページを取得します。
for message_batch in client.messages.batches.list(
    limit=20
):
    print(message_batch)

バッチ結果の取得

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

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

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

#!/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
            # リクエスト本体は再送信前に修正する必要があります
            echo "Validation error: $custom_id"
          else
            # リクエストは直接再試行できます
            echo "Server error: $custom_id"
          fi
          ;;
        "expired")
          echo "Expired: $line"
          ;;
      esac
    done
  done

.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は標準的なエラー形状に設定されます。

バッチ結果は入力順序と一致しない可能性があります

Message Batchのキャンセル

import anthropic

client = anthropic.Anthropic()

message_batch = client.messages.batches.cancel(
    MESSAGE_BATCH_ID,
)
print(message_batch)

応答はバッチをcanceling状態で表示します：

JSON

{
  "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 リクエストに同一の cache_control ブロックを含める
キャッシュエントリが 5 分のライフタイム後に期限切れになるのを防ぐため、リクエストの安定したストリームを維持する
できるだけ多くのキャッシュされたコンテンツを共有するようにリクエストを構造化する

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

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."}
                ]
            }
        }
    ]
}'

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

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

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

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

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

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

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

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

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

Message Batches API

Message Batches APIの仕組み

バッチの制限

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

バッチ処理できるもの

価格設定

Message Batches APIの使用方法

バッチの準備と作成

バッチの追跡

Message Batchの完了をポーリングする

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

バッチ結果の取得

Message Batchのキャンセル

Message Batches でプロンプトキャッシングを使用する

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

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

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

FAQ

バッチの処理にはどのくらいの時間がかかりますか?

Batches API はすべてのモデルで利用可能ですか?

Message Batches API を他の API 機能と一緒に使用できますか?

Message Batches API は価格にどのように影響しますか?

バッチを送信した後で更新できますか?

Message Batches API のレート制限はありますか? また、Messages API のレート制限と相互作用しますか?

バッチリクエストのエラーをどのように処理しますか?

Message Batches API はプライバシーとデータ分離をどのように処理しますか?

Message Batches API でプロンプトキャッシングを使用できますか?

Message Batches API

Message Batches APIの仕組み

バッチの制限

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

バッチ処理できるもの

価格設定

Message Batches APIの使用方法

バッチの準備と作成

バッチの追跡

Message Batchの完了をポーリングする

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

バッチ結果の取得

Message Batchのキャンセル

Message Batches でプロンプトキャッシングを使用する

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

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

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

FAQ

バッチの処理にはどのくらいの時間がかかりますか?

Batches API はすべてのモデルで利用可能ですか?

Message Batches API を他の API 機能と一緒に使用できますか?

Message Batches API は価格にどのように影響しますか?

バッチを送信した後で更新できますか?

Message Batches API のレート制限はありますか? また、Messages API のレート制限と相互作用しますか?

バッチリクエストのエラーをどのように処理しますか?

Message Batches API はプライバシーとデータ分離をどのように処理しますか?

Message Batches API でプロンプトキャッシングを使用できますか?