機能

バッチ処理

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

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

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

バッチ処理できるもの

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

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

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

バッチの処理には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.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-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になります。

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の一覧表示

一覧エンドポイントを使用して、ワークスペース内のすべての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-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番目のバッチリクエストの結果が1番目より先に返されています。結果を対応するリクエストと正しく照合するには、常に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-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."}
                ]
            }
        }
    ]
}'

この例では、バッチ内の両方のリクエストに同一のシステムメッセージと「高慢と偏見」の全文がcache_controlマーク付きで含まれており、キャッシュヒットの可能性を高めています。

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

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

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

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

予期しない動作が発生した場合：

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

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

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

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

FAQ

Was this page helpful?

機能

バッチ処理

大量のデータを処理する必要がある場合
即座のレスポンスが不要な場合
コスト効率を最適化したい場合
大規模な評価や分析を実行する場合

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

Message Batches API

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

Message Batches APIの仕組み

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

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

これは、即座の結果を必要としない一括操作に特に有用です。例えば：

大規模な評価：数千のテストケースを効率的に処理。
コンテンツモデレーション：大量のユーザー生成コンテンツを非同期で分析。
データ分析：大規模なデータセットに対するインサイトやサマリーの生成。
一括コンテンツ生成：さまざまな目的（例：商品説明、記事の要約）のための大量のテキスト作成。

バッチの制限事項

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

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

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

バッチ処理できるもの

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

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

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

料金

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

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-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は標準のエラー形式に設定されます。

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

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

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

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

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

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

予期しない動作が発生した場合：

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

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

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

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

FAQ

Was this page helpful?

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でプロンプトキャッシングを使用できますか？