Claudeバッチ処理(Batch API)は半額：キャッシュ併用の実額と使い方

ここで扱うのは、Claude APIへのリクエストをまとめて非同期で処理するMessage Batches API（公式日本語ドキュメントでの名称は「バッチ処理」）です。Claude Codeの/batchは、コードベース全体の変更を5〜30の単位に分けて並列のサブエージェントに実行させるコマンドで、Batch APIとは別物です。/batchを使っても、APIの料金は半額になりません。

2026年10月30日時点で、Batch APIの料金は入力、出力、キャッシュの書き込みと読み取りまで、すべてのトークン区分で標準の50%です。多くのバッチは1時間以内に終わりますが、最長24時間かかることがあり、その間に処理されなかったリクエストは期限切れになります。数分以内に結果がいらない評価、分類、抽出、一括書き換え、夜間レポートなら、client.messages.batches.createで投入し、processing_statusがendedになるまでポーリングし、結果をcustom_idで元データに戻す流れに切り替える価値があります。

ただし、半額がそのまま請求額の差になるとは限りません。長い共通プレフィックス（システムプロンプトや参照文書）を持つ処理では、通常呼び出し＋プロンプトキャッシュの方が、キャッシュなしのバッチより安くなります。Sonnet 5.5で1万件を試算すると、前者が$44.00、後者が$50.50でした。バッチの中でもキャッシュを使い、ヒット率が5分キャッシュで約21%を超えればキャッシュなしのバッチより安く、約39%を超えれば通常＋キャッシュも下回ります。

Claude Batch APIの料金：全トークン区分が標準の50%

バッチの割引は入力と出力だけでなく、キャッシュの書き込みと読み取りにも同じ50%がかかります。Claudeの料金ページは、キャッシュの倍率（5分の書き込み1.25倍、1時間の書き込み2倍、読み取りは多くのモデルで0.1倍、Opus 5.5とSonnet 5.5は0.05倍、Fable 5.1は0.025倍）が、Batch APIの割引やデータレジデンシーの倍率と重ねて適用されると説明しています。下の表の右端は、その倍率にバッチの50%を掛けた値です。

旧モデルのバッチ単価は、Opus 5・4.8・4.7・4.6・4.5が$2.50／$12.50、Sonnet 5が$1／$5、Sonnet 4.6・4.5が$1.50／$7.50、Haiku 4.5が$0.50／$2.50です（2026年10月30日時点、Claudeのバッチ処理ドキュメントの料金表）。米国内での推論を指定するinference_geo: "us"の1.1倍もバッチと重なり、Claude 4.6以降（Haiku 5.5を除く）は100万トークンのコンテキスト全体が割増なしの標準単価で、バッチ割引もウィンドウ全体にかかります。高速モードはバッチでは使えません。モデルごとの単価の詳しい比較は「Claude Fable 5.1のAPI料金：単価と月額の目安」と「Claude Sonnet 5.5のキャッシュ読み取り料金は$0.10：削減率の求め方」で比較できます。

1万件の処理でいくらになるか：通常・キャッシュ・バッチの比較

同じ処理でも、どの組み合わせで送るかで請求額は4倍以上変わります。2026年10月30日に、公式の定価で次の作業量を再計算しました。1件あたり共通プレフィックス3,000トークン＋固有の入力800トークン、出力250トークンのリクエストを1万件送る想定です。通常＋キャッシュはリクエストを順番に送ってほぼ100%ヒットする前提、バッチ内のキャッシュはミスのたびにプレフィックスを書き直す（書き込み料金が発生する）前提で計算しています。

どのモデルでも、ほぼ全件ヒットする通常＋キャッシュは、キャッシュなしのバッチより安くなります。この作業量では入力の8割近くが共通プレフィックスで、キャッシュ読み取りがそこを標準の5%（Sonnet 5.5の場合）まで下げるのに対し、バッチは全体を50%にするだけだからです。逆に、出力はこの作業量で通常料金の24.8%を占め、キャッシュではまったく下がりませんが、バッチなら半分になります。出力が長い処理、共通部分が短い処理ほど、キャッシュよりバッチの効果が大きくなります。

もう一つ見落としやすいのが、1時間キャッシュの書き込み料金です。ヒット率が30%しかないと、バッチ＋1時間キャッシュはキャッシュなしのバッチより高くつきます。一番安いのは、バッチの中でもキャッシュが高い率でヒットする組み合わせで、そのためには次の節の条件を満たす必要があります。

バッチ内のプロンプトキャッシュはヒット率約21%から得になる

バッチの中でキャッシュを使うと得になるのは、5分キャッシュならヒット率が約21%を超えたとき、1時間キャッシュなら約51%を超えたときです。バッチのリクエストは並行して順不同に処理されるため、Anthropicはキャッシュのヒットを「ベストエフォート」とし、実際のヒット率は30〜98%程度だとバッチ処理ドキュメントで説明しています。ミスしたリクエストは書き込み料金を払うので、ヒット率が低いと、キャッシュを付けない方が安くなります。

境目は、書き込み倍率をw、読み取り倍率をrとすると、ヒット率 ＞ (w − 1) ÷ (w − r) で求められます。5分キャッシュ（w = 1.25）では、Sonnet 5.5とOpus 5.5（r = 0.05）が20.8%、Haiku 5.5（r = 0.1）が21.7%、Fable 5.1（r = 0.025）が20.4%です。1時間キャッシュ（w = 2）では、それぞれ51.3%、52.6%、50.6%まで上がります。バッチの割引はすべての区分に同じ50%がかかるので、この境目はバッチでも通常呼び出しでも変わりません。

通常＋キャッシュより安くなる境目は、作業量によって変わります。前の節の条件では、バッチ＋5分キャッシュが通常＋キャッシュを下回るのは、Haiku 5.5で約32%、Sonnet 5.5とOpus 5.5で約39%、Fable 5.1で約42%以上のヒット率のときです。ヒット率を上げるために、Anthropicは全リクエストに同じcache_controlブロックを付けること、5分のエントリーが切れないように途切れずに送り続けること、共通部分をできるだけ多くすることを勧めています。共通文脈のあるバッチには1時間キャッシュも検討するよう書かれていますが、書き込みが2倍なので、5分ではエントリーが切れてヒット率が下がる場合に限って意味があります。max_tokens: 0でキャッシュを事前に温める方法は、バッチの中では使えません。cache_controlの書き方とTTLの選び方は「Claudeプロンプトキャッシュの使い方：5分/1時間の損益分岐と実測値」で扱っています。

最初のバッチを投入する：作成、ポーリング、custom_idで照合

バッチは、custom_idと通常のMessages APIのパラメーター（params）を組にしたリクエストの配列を1回で送り、終わるまで状態を確認し、結果をcustom_idで受け取る、という3段階で使います。APIキーをまだ持っていない場合は「Claude APIキーは無料？作成は無料、使う分は利用クレジットを購入」を先に読んでください。

1. 同じparamsで、通常のMessages APIに1件だけ送ってみます。バッチのパラメーターは非同期で検証されるため、形式の誤りは、バッチ全体が終わってからerroredとして返ってきます。
2. 各リクエストにcustom_idを付けます。英数字と-、_の1〜64文字で、同じバッチの中で重複できません。paramsにはmodel、max_tokens（1以上）、messagesを通常と同じ形で入れます。
3. client.messages.batches.create(requests=...)で投入し、返ってきたバッチIDを保存します。
4. client.messages.batches.retrieve(id)でprocessing_statusを確認します。処理中はin_progressで、request_countsはprocessing以外が0のままです。全件が終わるとendedに変わります。
5. client.messages.batches.results(id)で結果を1行ずつ読み、custom_idで元データに戻します。結果は入力した順番では返りません。

次のコードは、この流れに再送の振り分けまでを加えたものです。

import time
import anthropic

client = anthropic.Anthropic()  # ANTHROPIC_API_KEY を読む

def make_request(custom_id: str, text: str) -> dict:
    return {
        "custom_id": custom_id,  # 1〜64文字：英数字、- と _
        "params": {
            "model": "claude-haiku-5-5",
            "max_tokens": 300,
            "messages": [{"role": "user", "content": text}],
        },
    }

def run_batch(requests: list[dict], poll_seconds: int = 60) -> tuple[dict, list[str], list[str]]:
    batch = client.messages.batches.create(requests=requests)
    print("created", batch.id, batch.processing_status)
    while batch.processing_status != "ended":
        time.sleep(poll_seconds)
        batch = client.messages.batches.retrieve(batch.id)
        print("status", batch.processing_status, batch.request_counts)
    done, retry, fix = {}, [], []
    for item in client.messages.batches.results(batch.id):  # 順番は保証されない
        r = item.result
        if r.type == "succeeded":
            done[item.custom_id] = r.message.content[0].text
        elif r.type == "expired":
            retry.append(item.custom_id)  # モデルに届いていない。課金なし
        elif r.type == "errored" and r.error.error.type == "invalid_request_error":
            fix.append(item.custom_id)    # 同じ本文で再送しても再び失敗する
        elif r.type == "errored":
            retry.append(item.custom_id)  # サーバー側のエラー。そのまま再送できる
    return done, retry, fix

texts = {"doc-001": "要約してください：請求書の支払期限は30日です。",
         "doc-002": "要約してください：価格は税込みです。"}
done, retry, fix = run_batch([make_request(cid, t) for cid, t in texts.items()])
if retry:  # 再送できるものだけを新しいバッチで送り直す
    done2, _, _ = run_batch([make_request(cid, texts[cid]) for cid in retry])
    done.update(done2)

2026年10月30日、anthropic Python SDK 2.3.0で、このコードの流れを、公式ドキュメントのレスポンス形式どおりに作ったローカルのモックサーバーに対して実行しました。Anthropicのサーバーでバッチを処理したものではなく、確かめたのはコードの分岐です。処理時間、実際の検証メッセージ、課金はこのテストの対象外で、それらの記述は公式ドキュメントによります。5件のうち2件がsucceeded、api_errorのerrored1件とexpired1件が2回目のバッチで再送されて成功し、invalid_request_errorの1件は修正待ちとして残りました。モックは結果を逆順で返しましたが、custom_idで正しく照合でき、endedになるまでのrequest_countsはprocessing=5以外が0のままでした。TypeScriptの@anthropic-ai/sdk 1.3.0にも同じmessages.batches.create、retrieve、resultsがあります。

succeeded・errored・canceled・expiredの扱いと課金

バッチの結果は4種類で、課金されるのはsucceededだけです。errored、canceled、expiredはどれも料金がかからず、1件が失敗しても同じバッチの他のリクエストには影響しません。再送するかどうかは、erroredの中身で分かれます。

投入したバッチは中身を変更できません。間違いに気づいたらPOST /v1/messages/batches/{id}/cancelで取り消し、直したものを新しいバッチで送ります。取り消しはすぐに効くとは限らず、状態はcancelingを経てendedになり、それまでに終わった分の結果は取得できます。結果は、バッチを作成したときのAPIバージョンの形式で返ります。

Batch APIの上限：10万件・256MB・24時間・29日

1回のバッチに入れられるのは、10万件か256MBのどちらか先に達するまでです。公開当初の上限は1万件でしたが、2026年10月30日時点では10万件に上がっています。主な上限は次のとおりです。

ティアごとの値はClaude APIのレート制限ドキュメントによるもので、新しい組織はこれより低いEvaluationティアから始まることがあります。バッチの利用は、通常のMessages APIのレート制限には影響しません。同期呼び出しで429が出ている場合の切り分けは「Claude API の Rate Limit Reached は、先に制限の持ち主を特定する」を参照してください。バッチはClaude Consoleのワークスペース単位で管理され、同じワークスペースのAPIキーからしか見えません。並行処理のため、ワークスペースに設定した支出上限をわずかに超えることがあります。不要になったバッチは、処理が終わった後にDELETE /v1/messages/batches/{id}で削除できます。

バッチ処理が数時間かかる、期限切れになるとき

バッチの処理時間に保証はなく、24時間まではかかりうる前提で予定を組む必要があります。Anthropicの説明では、多くのバッチは1時間以内に終わりますが、処理は「その時点の需要とリクエスト量」に応じて遅くなることがあり、その場合は24時間後に期限切れになるリクエストが増えます。遅くなる幅についての数字は公表されていません。

外部の報告は、条件をそろえた計測ではありません。Hacker Newsのユーザー「erans」は2026年4月27日に、エージェントの各ターンをBatch API経由で送ったところ、1件だけのバッチでも通常90〜120秒ほどかかり、HaikuのバッチはSonnetやOpusより遅く感じたと書いています（本人も厳密な計測ではないとしています）。開発者向けサイトdevelopersdigestは、2026年10月18日更新の記事で、自分たちの計測では完了までの中央値が5〜30分だったとしています。Claudeのステータスページには、2025年以降にバッチに関する障害の記録はなく、記録に残っているのは2024年11月4日のエラー増加と、2024年11月6〜7日の処理遅延だけです。ただし、障害として記録されない程度の遅れはありえます。

期限切れになったリクエストは課金されないので、前の節のコードのようにcustom_idで拾い出して新しいバッチで送り直します。30万トークンの長い出力を有効にしたリクエストは、1件でも1時間を超えることがあります。数分以内に結果が必要な処理はバッチに向かないので、通常の呼び出しに戻し、過負荷時の再試行は「Claude APIの529 overloaded_error対処法：SDKの再試行と過負荷を制御する」の方法で制御します。

バッチに入れられるリクエスト、入れられないリクエスト

通常のMessages APIでできることの大半は、バッチでもそのまま使えます。種類の違うリクエストを1つのバッチに混ぜることもできます。使えないのは、ストリーミングや高速モードのように、その場で応答を返すことが前提の機能です。

ツール使用で実際に制約になるのは、1件のリクエストの中で、手元で実行するツールの結果を待てないことです。バッチの1件は1回のMessages API呼び出しなので、自分のコードでツールを実行して結果を返すループは、ターンごとに新しいリクエストとして送り直すことになります。サーバーツールはAnthropic側でループが回るため、同期呼び出しより多くの反復をしてからpause_turnで返ることがあります。拡張出力ベータが使えるのはOpus 5.5、Opus 5、Opus 4.8・4.7・4.6、Sonnet 5.5、Sonnet 5、Sonnet 4.6、Haiku 5.5で、経路はClaude APIとClaude Platform on AWSに限られます。

Bedrock・Vertex AI・ゲートウェイ経由でもバッチは半額になるか

Message Batches APIが一般提供されているのは、AnthropicのClaude API、Claude Platform on AWS、Anthropicが管理するGoogle Cloud上のClaudeの3つで、ここでは上の料金表どおりに半額になります。Amazon BedrockとGoogleが管理するVertex AIでは、Message Batches APIではなく各社のバッチ推論を使い、形式も料金の条件も別です。

Amazon Bedrockのバッチ推論は、AWSのBedrock料金ページで、Anthropicなど一部のモデルがオンデマンドより50%安いとされています。入力はS3に置いたJSONL（1行にrecordIdとmodelInput）で、Claudeでは1ジョブ100件以上、最大10万件・5GBです。2026年10月30日時点で、Bedrockのバッチ対応モデル一覧に載っているClaudeはOpus 5、Opus 4.6、Sonnet 4.6、Haiku 4.5などまでで、5.5世代とFableはありません。Bedrockは、Anthropicが運営するClaude Platform on AWSとは別のサービスです。

Vertex AIのバッチ予測は、BigQueryのテーブルかCloud StorageのJSONLを入力にし、グローバルエンドポイントには対応していません。Vertex AIのClaudeバッチ予測ドキュメント（2026年10月28日更新）にはSonnet 5.5、Opus 5.5、Haiku 5.5、Fable 5.1が載っていますが、割引率はGoogle Cloudの料金ページで、使うモデルごとに確認してください。

/v1/messages/batchesを持たないAPIゲートウェイでは、バッチ自体が使えません。2026年10月30日にlaozhang.aiのAPIキーで/v1/messages/batchesの一覧取得、作成、取得の3つを呼び出すと、いずれもHTTP 404「Invalid URL」が返り、課金もされませんでした。ゲートウェイ経由でClaudeを使っている場合は、バッチ処理だけAnthropicのAPIキーで直接送る構成になります。

注記：laozhang.ai は当ブログ運営チームの自社サービスです。その料金は中立的な比較ではなく、自社の提示価格です。

Claude Batch APIのよくある質問

Claude Codeの作業をBatch APIで半額にできますか？

Claude Code標準の/batchは並列エージェントでコードを変更する機能で、Batch APIには送りません。Claude Codeから重い処理をBatch APIに回したい場合は、第三者が公開しているMCPサーバー＋スキルのs2-streamstore/claude-batch-toolkitのような仕組みが必要です。このツールキットは、標準の/batchと名前が重なったため、スキル名を/batchyに変えています。既定のモデルはclaude-opus-4-6と古いままなので、使う前に設定を確認してください。APIとClaude Codeのどちらで処理するかは「Claude APIとClaude Codeの違いと使い分け」で整理しています。

MaxプランのAPIクレジットはバッチ処理にも使えますか？

使えます。2026年10月8日時点のClaudeヘルプセンターの説明では、Max 5x（月$100）、Max 20x（月$200）、Teamプラン（1席あたり月$20のStandard、月$100のPremium）に付く月次のAPIクレジットはMessage Batches APIを含むClaude APIに充てられ、プラン加入から7日後にClaude Consoleの組織をリンクして受け取ります。プランごとの上限とクレジットの種類は「Claudeの使用制限プラン別一覧：5時間・週次上限と3種類のクレジット」にあります。

バッチの完了をWebhookで受け取れますか？

2026年10月30日時点で、Message Batches APIのドキュメントとAPIリファレンスにWebhookの記載はなく、公式のサンプルもretrieveでprocessing_statusを定期的に確認する方法です。手作業で確認するなら、Claude Consoleのワークスペースのバッチ一覧でも状態が見られます。多くのバッチは1時間以内に終わるので、上のコードのように60秒ごとの確認で足ります。