Loading...
    • ビルド
    • 管理
    • モデルと料金
    • クライアントSDK
    • APIリファレンス
    Search...
    ⌘K
    はじめに
    Claudeの概要クイックスタート
    Claudeで構築する
    機能概要Messages APIの使用停止理由の処理
    モデルの機能
    拡張思考適応的思考エフォート高速モード(ベータ:リサーチプレビュー)構造化出力引用ストリーミングメッセージバッチ処理検索結果ストリーミング拒否多言語サポート埋め込み
    ツール
    概要ツール使用の仕組みウェブ検索ツールウェブフェッチツールコード実行ツールメモリツールBashツールコンピューター使用ツールテキストエディタツール
    ツールインフラ
    ツール検索プログラムによるツール呼び出し細粒度ツールストリーミング
    コンテキスト管理
    コンテキストウィンドウコンパクションコンテキスト編集プロンプトキャッシュトークンカウント
    ファイルの操作
    Files APIPDFサポート画像とビジョン
    スキル
    概要クイックスタートベストプラクティスエンタープライズ向けスキルAPIのスキル
    MCP
    リモートMCPサーバーMCPコネクター
    プロンプトエンジニアリング
    概要プロンプトのベストプラクティスConsoleプロンプトツール
    テストと評価
    成功の定義と評価の構築ConsoleでのEvaluation Toolの使用レイテンシの削減
    ガードレールの強化
    幻覚の低減出力の一貫性向上ジェイルブレイクの軽減プロンプトリークの低減
    リソース
    用語集
    リリースノート
    Claude Platform
    Console
    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の使用方法

    バッチ処理は、大量のリクエストを効率的に処理するための強力なアプローチです。リクエストを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. バッチは非同期で処理され、各リクエストは独立して処理されます。

    Was this page helpful?

    • Message Batches APIの仕組み
    • Message Batches APIの使用方法
    • すべてのMessage Batchをリストする
    • Message Batch のキャンセル
    • Message Batches でプロンプトキャッシングを使用する
    • FAQ
  1. バッチのステータスをポーリングして、すべてのリクエストの処理が終了したときに結果を取得できます。
  2. これは、以下のような即座の結果を必要としないバルク操作に特に有用です:

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

    バッチの制限

    • 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.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の処理ステータスを持ちます。

    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が必要です。バッチのステータスを定期的にチェックするポーリングループを実装して、処理が終了するまで待機できます:

    #!/bin/sh
    # ...
    until [[ $(curl -s "https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID" \
              --header "x-api-key: $ANTHROPIC_API_KEY" \
              --header "anthropic-version: 2023-06-01" \
              | grep -o '"processing_status":[[:space:]]*"[^"]*"' \
              | cut -d'"' -f4) == "ended" ]]; do
        echo "Batch $MESSAGE_BATCH_ID is still processing..."
    # ...
        sleep 60
    done
    
    echo "Batch $MESSAGE_BATCH_ID has finished processing"

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

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

    #!/bin/sh
    
    if ! command -v jq &> /dev/null; then
        echo "Error: This script requires jq. Please install it first."
        exit 1
    fi
    
    BASE_URL="https://api.anthropic.com/v1/messages/batches"
    
    has_more=true
    after_id=""
    
    while [ "$has_more" = true ]; do
        # Construct URL with after_id if it exists
        if [ -n "$after_id" ]; then
            url="${BASE_URL}?limit=20&after_id=${after_id}"
        else
            url="$BASE_URL?limit=20"
        fi
    
        response=$(curl -s "$url" \
                  --header "x-api-key: $ANTHROPIC_API_KEY" \
                  --header "anthropic-version: 2023-06-01")
    
        # Extract values using jq
        has_more=$(echo "$response" | jq -r '.has_more')
        after_id=$(echo "$response" | jq -r '.last_id')
    
        # Process and print each entry in the data array
        echo "$response" | jq -c '.data[]' | while read -r entry; do
            echo "$entry" | jq '.'
        done
    done

    バッチ結果の取得

    バッチ処理が終了すると、バッチ内の各 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_error" ]; 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-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 ステータスで終了し、キャンセル前に処理されたリクエストの部分的な結果が含まれる場合があります。

    #!/bin/sh
    # ...
    curl --request POST https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/cancel \
        --header "x-api-key: $ANTHROPIC_API_KEY" \
        --header "anthropic-version: 2023-06-01"

    レスポンスはバッチが 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. できるだけ多くのキャッシュされたコンテンツを共有するようにリクエストを構造化する

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

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

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

    拡張出力(ベータ版)

    output-300k-2026-03-24 ベータヘッダーは、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%)が適用されます。

    curl https://api.anthropic.com/v1/messages/batches \
         --header "x-api-key: $ANTHROPIC_API_KEY" \
         --header "anthropic-version: 2023-06-01" \
         --header "anthropic-beta: output-300k-2026-03-24" \
         --header "content-type: application/json" \
         --data \
    '{
        "requests": [
            {
                "custom_id": "long-form-request",
                "params": {
                    "model": "claude-opus-4-6",
                    "max_tokens": 300000,
                    "messages": [
                        {"role": "user", "content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices."}
                    ]
                }
            }
        ]
    }'

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

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

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

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

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

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

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


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

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

    • 結果の可用性: バッチ結果は、バッチ作成後 29 日間利用可能で、取得と処理に十分な時間があります。


    データ保持

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

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

    FAQ