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

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

自分の処理はBatch APIに向くか

判断の軸は1つで、結果を待てるかどうかです。同期のMessages APIは今すぐ返ります。Batch APIは安く、ただし返ってくる時刻を決められません。

迷うのは、Web検索を多用する調査バッチのような中間の処理です。Web検索は組織単位でスロットリングされるため、バッチでも動きますが完了が遅れることがあります。急ぎでない調査ならBatch API、急ぐなら同期APIと考えると切り分けられます。

割引額の見積もり方

割引の大きさは、トークン量に単価をかければ出ます。たとえばSonnet 5.5で、1件あたり入力2,000トークン・出力500トークンの処理を1万件流す場合を考えます。合計は入力2,000万トークン、出力500万トークンです。

バッチの単価は入力$1、出力$5(いずれも100万トークンあたり)なので、入力が$20、出力が$25で合計$45です。同じ処理を同期で送ると標準価格はこの2倍なので$90になり、差額は$45です。これは仮の条件での計算で、実際の差額は自分のトークン量で決まります。

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

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

上限を超えるデータは、複数のバッチに分割します。

対応モデル

稼働中のモデルはすべて対象です。中心はClaude Fable 5.1・Opus 5.5・Sonnet 5.5・Haiku 4.5です。Fable 5・Opus 5・Sonnet 5・Opus 4.8〜4.5・Sonnet 4.6も使えます。非推奨のSonnet 4.5も、提供終了までは使えます。

退役したモデルは別です。Opus 4.1はClaude APIで2026年8月5日に、Sonnet 4とOpus 4は2026年6月15日に提供を終えています。Bedrockなど他のクラウドでは残っている場合があり、料金ページにも退役済みと例外が併記されています。新規の実装では現行モデルを選びます。

Workspaceとレート制限

バッチはWorkspace単位に紐づきます。あるWorkspaceで作成したバッチは、同じWorkspaceのAPIリクエストからしか取得できません。複数のWorkspaceを使い分けているなら、どのキーでバッチを作るかを先に決めておきます。

Batch APIのレート制限はMessages APIとは別枠で、全モデル共通です。制限は分あたりのリクエスト数と、処理待ちキューに積めるバッチ内リクエスト数の2種類です。キューの上限は利用ティアで次のように変わります。

Startティアでは、10万件のバッチを3本続けて送ると、キューの上限(20万件)に当たる可能性があります。大きなデータは、キューの空きを見ながら小分けにして投入する設計が安全です。需要や自分のリクエスト量によっては処理が遅れ、24時間で期限切れになる件数が増えることもあります。

料金は標準の50%引き

入力・出力トークンの両方が、同期呼び出しの標準価格に対して一律50%になります。下の表の単価は、すでに割引後の数字です。

表にないモデルでは、Opus 4.8〜4.5が$2.50と$12.50、Sonnet 4.6と4.5が$1.50と$7.50です。Sonnet 4.5は非推奨で、2026年11月30日に提供終了予定です。Prompt Cachingの割引とは重ね掛けできます。方法は後述します。

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

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

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

• stream: true
• speed(Fast mode)
• max_tokens: 0

バッチ内の各リクエストはmax_tokensを1以上にします。

バッチの流れ

全体の流れは4段階です。

バッチを作成する

各リクエストには一意の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-5",
          "max_tokens": 1024,
          "messages": [{"role": "user", "content": "Hello, world"}]
        }
      }
    ]
  }'

作成直後のレスポンスでは、processing_statusがin_progressになります。各リクエストのparamsの検証は非同期で行われ、バリデーションエラーはバッチ全体の処理が終わってから返ります。実装を始める前に、同じリクエストの形をMessages APIで1件テストしておくと、原因を切り分けやすくなります。

処理状況を確認する

作成時に返るidを使って、状況を定期的に確認します。公式のコード例は、60秒間隔で確認しています。

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'

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

結果を取得する

処理が終わったバッチには、results_urlから結果ファイルをダウンロードできます。サイズが大きくなりうるため、一括ダウンロードよりストリーミング取得が推奨されています。組織の権限設定次第では、Consoleからダウンロードすることもできます。

各リクエストの結果は4種類のいずれかです。利用ポリシーによる拒否もsucceededとして返ります。詳しくはBatch APIの拒否は成功扱いになる落とし穴にあります。

失敗した分だけ再投入する

errored・canceled・expiredの3種類は課金されません。つまり、失敗した分を新しいバッチで送り直しても、二重に払うことはありません。バッチ全体をやり直す必要はなく、succeeded以外のcustom_idだけを抜き出せば足ります。

結果ファイルの各行には、custom_idとresult.typeが入っています。次のコマンドで、成功しなかったリクエストのIDを一覧できます。

RESULTS_URL=$(curl -s "https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  | jq -r '.results_url')
 
curl -s "$RESULTS_URL" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  | jq -r 'select(.result.type != "succeeded") | "\(.result.type) \(.custom_id)"'

出力された種類で、次の手を分けます。expiredは期限内に処理が回らなかっただけなので、そのまま再投入できます。erroredは、リクエスト自体が不正なのか、サーバー側の一時的な失敗なのかをエラー情報で見分けます。invalid_request_errorなら内容を直し、そうでなければ同じ内容で再送します。

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

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

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

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

バッチは処理に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は組織単位でスロットリングされます。スロットルされたリクエストは自動的にリトライされるため、利用者側での再送処理は基本的に不要です。

出力を30万トークンまで伸ばす拡張出力

output-300k-2026-03-24ベータヘッダーを付けると、バッチのmax_tokens上限を300,000まで引き上げられます。対象はOpus 5.5・Opus 5・Opus 4.8・4.7・4.6、Sonnet 5.5・Sonnet 5・Sonnet 4.6です。

この機能はBatch APIでのみ提供され、同期のMessages APIでは使えません。書籍規模の長文生成や、大規模な構造化データ抽出に向きます。

30万トークン規模の生成は、完了まで1時間を超えることがあります。24時間の処理枠を踏まえて、送信タイミングを決めます。利用できるのはClaude APIとClaude Platform on AWSで、Amazon Bedrock・Google Cloud・Microsoft Foundryでは使えません。

よくあるつまずき

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

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

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

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

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

よくある質問

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

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

保存されたバッチのデータは削除できますか

リクエストとレスポンスは、バッチ作成から最大29日間保存されます。処理が終わったあとなら、いつでもDELETE /v1/messages/batches/{batch_id}で削除できます。処理中のバッチを消したいときは、先にキャンセルしてから呼びます。

Consoleで結果をダウンロードできません

ダウンロード機能は、組織単位でもWorkspace単位でも無効にできます。見られない場合は、管理者に権限設定を確認します。

まとめ

判断の分かれ目は、結果が数時間遅れても困らないかどうかです。困らない処理は、同期APIとの差額をトークン量から試算し、失敗分だけ再投入する前提で組むと運用が軽くなります。契約書PDFを台帳に落とす実例は契約台帳をPDFから一括抽出する手順にあります。