Claude Batch APIの使い方 — 料金50%引きと非同期処理

Claude Batch APIは、Messages APIへのリクエストを1件ずつ即時に送る代わりに、まとめて非同期で処理させる仕組みです。入力・出力トークンともに標準料金の50%になり、多くのバッチは1時間以内に完了します。評価データの一括処理やコンテンツの大量生成など、即座の応答が要らないタスクに向きます。

Batch APIとは — 何ができるのか

Batch API(Message Batches API)は、POST /v1/messages/batchesに複数のMessagesリクエストをまとめて送信する機能です。Anthropic側が非同期に処理し、各リクエストは独立して扱われます。失敗した1件が他のリクエストに影響することはありません。

用途は幅広いです。大量のテストケースを流す評価、ユーザー生成コンテンツを非同期で分析するモデレーション、大規模データセットの要約生成、商品説明・記事要約の量産などが該当します。処理は最大24時間以内に終わり、多くのケースではもっと早く完了します。

使い始める前に確認すること

Batch APIを使うには、通常のAnthropic APIキーがあれば十分です。専用の申請や別契約は不要で、Anthropic API完全ガイドで扱っているキー発行手順がそのまま使えます。

対応モデルは現行の稼働モデルすべてです。中心はClaude Fable 5・Opus 5・Sonnet 5・Haiku 4.5です。旧世代のOpus 4.8〜4.5・Sonnet 4.6も引き続き利用できます。古い世代のうちOpus 4.1は非推奨(まだ動きますが新規利用は避ける対象)、Opus 4はGoogle Cloudを除き、Sonnet 4はBedrockとGoogle Cloudを除き、提供終了済みです。いずれもBatch APIの技術的な対象には含まれますが、新規実装では現行モデルを選ぶのが妥当です。

バッチはWorkspace単位に紐づきます。あるWorkspaceで作成したバッチは、そのWorkspaceに属するAPIキーからしか参照できません。組織内で複数のWorkspaceを使い分けているなら、どのキーでバッチを作るかを先に決めておく必要があります。

料金は標準の50%引き

Batch APIの最大の価値は料金です。入力・出力トークンの両方が、同期呼び出しの標準価格に対して一律50%になります。

この単価はすでに50%割引後の数字です。同じリクエストを同期のMessages APIで送ると、この2倍のコストがかかります。Prompt Cachingの割引と重ね掛けできるため、両方を組み合わせるとさらに単価を下げられます。詳しくは後述します。

送信できるリクエストとできないリクエスト

Messages APIに送れるリクエストのほとんどは、そのままバッチに含められます。Vision、Tool use(サーバー側ツールを含む)、システムメッセージ、マルチターンの会話、Extended thinking、ほとんどのベータ機能が対象です。1つのバッチの中に、異なる種類のリクエストを混ぜても構いません。

一方で、次のパラメータを含めるとバリデーションエラーになります。

バッチを作成する

バッチはリクエストのリストをrequestsパラメータに渡して作成します。各リクエストには一意のcustom_id(英数字・ハイフン・アンダースコアのみ、1〜64文字)と、通常のMessages APIパラメータを含むparamsオブジェクトが必要です。

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-5",
          "max_tokens": 1024,
          "messages": [{"role": "user", "content": "Hello, world"}]
        }
      }
    ]
  }'

作成直後のレスポンスでは、processing_statusがin_progressになります。実装を始める前に、同じリクエストの形をMessages APIで1件テストしておくと、バリデーションエラーの原因切り分けが楽になります。バッチ全体のバリデーションは処理完了後にまとめて返るため、事前確認を省くと24時間待ってからエラーに気づく事態になりかねません。

処理状況をポーリングで確認する

バッチのidを使って、処理状況を定期的に確認します。processing_statusはin_progressから始まり、全リクエストの処理が終わるとendedになります。

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" \
  | jq -r '.processing_status'

ポーリングの間隔は60秒程度が一般的です。バッチ一覧はページネーション対応で、after_id / before_idをカーソルにして次ページを取得します。公式SDKとant CLIはこの自動ページングを内蔵しているため、自前でカーソル管理を書く必要はありません。

結果を取得する

処理が終わったバッチには、results_urlから結果ファイルをダウンロードできます。ファイルは.jsonl形式で、1行が1リクエストの結果です。サイズが大きくなりうるため、一括ダウンロードよりストリーミング取得が推奨されています。

各リクエストの結果は4種類のいずれかになります。

Prompt Cachingと組み合わせてさらにコストを下げる

Batch APIはPrompt Cachingと併用でき、割引を重ね掛けできます。ただしバッチは非同期・並行処理のため、キャッシュヒットはベストエフォートです。実際のヒット率はトラフィックのパターンによって30%から98%まで幅があります。

ヒット率を上げるには3点が効きます。

• バッチ内の全リクエストで同一のcache_controlブロックを使う
• キャッシュエントリが5分の寿命内に失効しないよう、一定のリクエスト流量を保つ
• リクエスト間でできるだけ多くのコンテキストを共有する構造にする

バッチは処理に時間がかかるため、1時間TTLのキャッシュのほうがヒット率で有利になるケースが多くあります。この設計判断はPrompt Cachingの仕組みで詳しく扱っています。

Tool useと拡張機能はどこまで動くか

Web検索・Web取得・コード実行・MCPコネクタ・advisor・tool searchを含む、すべてのサーバーサイドツールがバッチ内で動きます。バッチワーカーは同期のMessages APIと同じサーバーサイドのエージェントループを実行します。ツール呼び出しの実装パターン自体はAdvanced Tool Useと共通です。

同期リクエストと違うのは、開いたままの接続を維持する必要がないため、1ターンあたりの反復回数を同期リクエストより多く進めてからstop_reason: "pause_turn"を返す点です。pause_turnが返った場合はターンが終わっていないので、一時停止したアシスタントの内容を含めて続きのリクエストを送ります。web_searchは組織単位でスロットリングされ、スロットルされたリクエストは自動的にリトライされるため、利用者側での再送処理は基本的に不要です。

拡張出力(ベータ)を使うと、output-300k-2026-03-24ベータヘッダーでバッチのmax_tokens上限を300,000まで引き上げられます。対象はOpus 5・Opus 4.8・4.7・4.6、Sonnet 5・Sonnet 4.6です。この機能はBatch APIでのみ提供され、同期のMessages APIでは使えません。書籍規模の長文生成や大規模な構造化データ抽出に向きますが、30万トークン規模の生成は完了まで1時間を超えることがあるため、24時間の処理枠を踏まえて送信タイミングを設計します。利用できるプラットフォームにも制限があり、Claude APIとClaude Platform on AWSでは使えますが、Amazon Bedrock・Google Cloud・Microsoft Foundryでは利用できません。

いつBatch APIを使うべきか

同期のMessages APIとBatch APIは、即時性とコストのトレードオフで選びます。

よくあるつまずき

サイズ超過での413エラー: バッチ全体が256MBを超えるとrequest_too_largeエラーになります。これはMessage Batches API固有のリクエストサイズ上限で、超えた場合は複数のバッチに分割します。

custom_idの重複: 同一バッチ内でcustom_idが重複すると、結果を正しく紐づけられなくなります。作成前に一意性を検証しておくと安全です。

29日のカウント起点を勘違いする: 結果が閲覧できる期間は、処理が終わった時刻(ended_at)からではなく、バッチを作成した時刻(created_at)から29日です。処理に時間がかかったバッチほど、実質的な閲覧可能期間は短くなります。

キャンセル済みバッチの扱い: バッチをキャンセルしても、キャンセルが確定するまではcanceling状態が続きます。キャンセルが確定したended状態のバッチには、キャンセルされるまでに処理済みだった分の部分的な結果が残ることがあります。

max_tokens: 0のキャッシュ事前ウォームアップは使えない: 同期リクエストでは有効なパターンですが、バッチでは非対応です。バッチ内で書き込んだ一時的な(ephemeral)キャッシュは、後続リクエストが実行される前に失効しやすいためです。

Workspaceの支出上限をわずかに超えることがある: バッチは高いスループットで並行処理されるため、Workspaceに設定した支出上限をわずかに超過する場合があります。上限ギリギリの運用をしている場合は余裕を見て設定します。

よくある質問

バッチの内容は送信後に変更できますか

できません。一度送信したバッチは変更できないため、修正が必要な場合は現在のバッチをキャンセルして新しいバッチを送信し直します。キャンセルは即座に反映されるとは限りません。

バッチの結果はConsoleからでも見られますか

見られます。組織の権限設定次第では、Consoleからバッチ結果をダウンロードすることも可能です。ダウンロード機能自体は組織単位・Workspace単位で無効化できるため、閲覧できない場合は管理者に権限設定を確認します。

Batch APIのレート制限はMessages APIと共有されますか

共有されません。Batch APIには、HTTPリクエスト数と処理待ちのバッチ内リクエスト数それぞれに独自のレート制限があり、Messages APIのレート制限には影響しません。

バッチのデータはいつまで保存されますか

リクエストとレスポンスのデータは、バッチ作成から最大29日間保存されます。処理中のバッチを削除したい場合は、先にキャンセルしてからDELETE /v1/messages/batches/{batch_id}エンドポイントを呼びます。

エラーが起きたリクエストはどう扱えばいいですか

結果を取得すると、各リクエストのresultフィールドにsucceeded・errored・canceled・expiredのいずれかが入ります。erroredの場合はエラー情報が付随します。invalid_request_errorのようにリクエスト自体の修正が要るのか、リトライで解決するサーバーエラーなのかを判定してから対応します。

まとめ

Batch APIは、即時性を手放す代わりに入力・出力とも標準料金の50%でMessagesリクエストを処理する非同期の仕組みです。100,000リクエストまたは256MBまでを1バッチにまとめられ、多くは1時間以内、遅くとも24時間以内に完了します。結果はcustom_idで紐づけて取得し、Prompt Cachingと組み合わせればコストをさらに圧縮できます。評価・データ分析・大量コンテンツ生成のように「今すぐ返ってこなくていい」処理があるなら、まず同期APIとの料金差を試算してみる価値があります。