モデルの機能

バッチ処理

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

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

これは、以下のような即時結果を必要としない一括操作に特に有用です：

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

バッチの制限事項

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

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

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

バッチ処理できるもの

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

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

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

バッチの処理には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.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 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を一覧表示する

一覧エンドポイントを使用して、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-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番目のバッチリクエストの結果が最初のものより先に返されています。結果を対応するリクエストと正しく照合するには、常に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でのPrompt Cachingの使用

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

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

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

バッチでのPrompt Cachingの実装例：

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でマークされた「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キー、またはConsoleでワークスペースのバッチを表示する権限を持つユーザーのみがアクセスできます。
結果の可用性: バッチ結果はバッチ作成後29日間利用可能で、取得と処理に十分な時間が確保されています。

データ保持

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

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

FAQ

Was this page helpful?

モデルの機能

バッチ処理

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

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

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

Message Batches APIの仕組み

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

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

これは、以下のような即時結果を必要としない一括操作に特に有用です：

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

バッチの制限事項

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

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

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

バッチ処理できるもの

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

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

バッチ内の各リクエストは独立して処理されるため、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.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 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でのPrompt Cachingの使用

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

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

バッチでのPrompt Cachingの実装例：

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キー、またはConsoleでワークスペースのバッチを表示する権限を持つユーザーのみがアクセスできます。
結果の可用性: バッチ結果はバッチ作成後29日間利用可能で、取得と処理に十分な時間が確保されています。

データ保持

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

FAQ

Was this page helpful?

Message Batches API

Message Batches APIの仕組み

バッチの制限事項

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

バッチ処理できるもの

料金

Message Batches APIの使い方

バッチの準備と作成

バッチの追跡

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

すべてのMessage Batchを一覧表示する

バッチ結果の取得

Message Batchのキャンセル

Message BatchesでのPrompt Cachingの使用

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

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

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

データ保持

FAQ

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

Batches APIはすべてのモデルで利用できますか？

Message Batches APIを他のAPI機能と組み合わせて使用できますか？

Message Batches APIは価格にどのような影響を与えますか？

送信後にバッチを更新できますか？

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

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

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

Message Batches APIでPrompt Cachingを使用できますか？

Message Batches API

Message Batches APIの仕組み

バッチの制限事項

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

バッチ処理できるもの

料金

Message Batches APIの使い方

バッチの準備と作成

バッチの追跡

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

すべてのMessage Batchを一覧表示する

バッチ結果の取得

Message Batchのキャンセル

Message BatchesでのPrompt Cachingの使用

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

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

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

データ保持

FAQ

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

Batches APIはすべてのモデルで利用できますか？

Message Batches APIを他のAPI機能と組み合わせて使用できますか？

Message Batches APIは価格にどのような影響を与えますか？

送信後にバッチを更新できますか？

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

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

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

Message Batches APIでPrompt Cachingを使用できますか？