Loading...
    • 構築
    • 管理
    • モデルと価格
    • クライアントSDK
    • APIリファレンス
    Search...
    ⌘K
    最初のステップ
    Claudeの紹介クイックスタート
    Claudeで構築
    機能概要Messages APIの使用Claude 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.7$2.50 / MTok$12.50 / MTok
    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。1~64文字である必要があり、英数字、ハイフン、アンダースコアのみを含む必要があります(^[a-zA-Z0-9_-]{1,64}$に一致)。
    • 標準的なMessages APIパラメータを含むparamsオブジェクト

    このリストをrequestsパラメータに渡すことでバッチを作成できます:

    from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
    from anthropic.types.messages.batch_create_params import Request
    
    client = anthropic.Anthropic()
    
    message_batch = client.messages.batches.create(
        requests=[
            Request(
                custom_id="my-first-request",
                params=MessageCreateParamsNonStreaming(
                    model="claude-opus-4-7",
                    max_tokens=1024,
                    messages=[
                        {
                            "role": "user",
                            "content": "Hello, world",
                        }
                    ],
                ),
            ),
            Request(
                custom_id="my-second-request",
                params=MessageCreateParamsNonStreaming(
                    model="claude-opus-4-7",
                    max_tokens=1024,
                    messages=[
                        {
                            "role": "user",
                            "content": "Hi again, friend",
                        }
                    ],
                ),
            ),
        ]
    )
    
    print(message_batch)

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

    import time
    
    client = anthropic.Anthropic()
    
    MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"
    
    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はページネーションをサポートし、必要に応じて自動的に追加ページを取得します:

    client = anthropic.Anthropic()
    
    # Automatically fetches more pages as needed.
    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 でも利用できます。結果のサイズが大きい可能性があるため、すべてを一度にダウンロードするのではなく、結果をストリーミングすることをお勧めします。

    client = anthropic.Anthropic()
    
    # Stream results file in memory-efficient chunks, processing one at a time
    for result in client.messages.batches.results(
        "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
    ):
        match result.result.type:
            case "succeeded":
                print(f"Success! {result.custom_id}")
            case "errored":
                if result.result.error.error.type == "invalid_request_error":
                    # Request body must be fixed before re-sending request
                    print(f"Validation error {result.custom_id}")
                else:
                    # Request can be retried directly
                    print(f"Server error {result.custom_id}")
            case "expired":
                print(f"Request expired {result.custom_id}")

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

    client = anthropic.Anthropic()
    
    MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"
    
    message_batch = client.messages.batches.cancel(
        MESSAGE_BATCH_ID,
    )
    print(message_batch)

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

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

    from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
    from anthropic.types.messages.batch_create_params import Request
    
    client = anthropic.Anthropic()
    
    message_batch = client.messages.batches.create(
        requests=[
            Request(
                custom_id="my-first-request",
                params=MessageCreateParamsNonStreaming(
                    model="claude-opus-4-7",
                    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.",
                        }
                    ],
                ),
            ),
            Request(
                custom_id="my-second-request",
                params=MessageCreateParamsNonStreaming(
                    model="claude-opus-4-7",
                    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 の完全なテキストが含まれています。

    拡張出力(ベータ版)

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

    from anthropic.types.beta.message_create_params import MessageCreateParamsNonStreaming
    from anthropic.types.beta.messages.batch_create_params import Request
    
    client = anthropic.Anthropic()
    
    message_batch = client.beta.messages.batches.create(
        betas=["output-300k-2026-03-24"],
        requests=[
            Request(
                custom_id="long-form-request",
                params=MessageCreateParamsNonStreaming(
                    model="claude-opus-4-7",
                    max_tokens=300_000,
                    messages=[
                        {
                            "role": "user",
                            "content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices.",
                        }
                    ],
                ),
            ),
        ],
    )
    
    print(message_batch)

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

    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