Claude Batch APIで300k出力を得る方法 — output-300k-2026-03-24

Message Batches APIでは、anthropic-beta: output-300k-2026-03-24 ヘッダーを付けると max_tokens の上限が30万トークンまで上がります。同期のMessages APIの最大出力は128Kトークンなので、1回の生成で2倍以上の長さを書かせられる計算です。

ただし条件がいくつかあります。対象モデルが限られ、同期APIでは使えず、Bedrock・Google Cloud・Foundryにも来ていません。1回の生成に1時間を超えることもあるため、24時間の処理枠に収める設計も要ります。

30万トークン出力とは何か

拡張出力(extended output)は、Message Batches API専用のベータ機能です。ヘッダーを付けたバッチでは、対象モデルの max_tokens を最大300,000まで指定できます。通常の上限である128kトークンを超える出力を、1ターンで生成するための仕組みです。

バッチAPI全般の仕組みと料金体系はClaude Batch APIの使い方にまとまっています。この記事は、その上で300k出力を使うための条件と運用に絞ります。

想定されている用途は次の4つです。

• 書籍1冊ぶんの下書きや技術ドキュメント
• 網羅的な構造化データの抽出
• 大きなコード生成の雛形
• 長い推論の連鎖

先に押さえたい条件を表にまとめます。

対象モデルと上限の一覧

対象は8モデルです。Opus 5.5・Opus 5・Opus 4.8・Opus 4.7・Opus 4.6・Sonnet 5.5・Sonnet 5・Sonnet 4.6が30万トークンまで受け付けます。

対象外の側も確認しておきます。出力上限表では、次のように分かれています。

Fable系は対象の8モデルに入っていません。最上位モデルの出力上限が、Opusより低くなる場面がある点に注意が必要です。Fable 5とOpus 5の違いはFable 5とOpus 5の比較にまとまっています。世代ごとの一覧はClaudeモデルラインナップで確認できます。

リクエストの書き方

変更点は2つだけです。ベータヘッダーを付けることと、max_tokens に300000を指定することです。

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

SDKではベータ側の名前空間を使います。Pythonなら client.beta.messages.batches.create に betas 引数でヘッダーを渡します。ドキュメントのサンプルに沿った形は次のとおりです。

import anthropic
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-5-5",
                max_tokens=300_000,
                messages=[{"role": "user", "content": "..."}],
            ),
        ),
    ],
)
print(message_batch)

TypeScriptでも同じ考え方で、client.beta.messages.batches.create の betas に "output-300k-2026-03-24" を渡します。通常のバッチの作り方や結果の取得はMessage Batches SDKの実装ガイドが詳しいので、ここでは差分だけを押さえれば足ります。

使えない場所を先に確認する

この機能は同期のMessages APIにはありません。対話的に呼び出すコードへ max_tokens: 300000 と書いても、同期側の上限が変わるわけではありません。Claude Codeの出力上限の設定はCLAUDE_CODE_MAX_OUTPUT_TOKENSの解説で扱っています。

クラウド事業者経由の利用にも制限があります。提供状況は次のとおりです。

• Claude APIとClaude Platform on AWSでは使える
• Amazon Bedrock・Google Cloud・Microsoft Foundryでは使えない

Bedrock上でClaudeを使っている組織は、この機能のためだけにClaude APIへの経路を別に用意する必要があります。データの置き場所や契約の都合と合わせて、経路の追加が許されるかを先に確かめておく必要があります。

思考トークンは300kの内側で数えられる

推論を伴う長い出力では、思考(thinking)のトークンも max_tokens に含まれます。思考の中身を返さない設定でも、思考に使ったトークンは出力トークンとして課金されます。

つまり max_tokens: 300000 は、思考と本文の合計の上限です。深く考えさせるほど、本文に回せる枠は減ります。長い推論の連鎖を用途にするなら、本文に必要な量を先に見積もり、その残りを思考の余地として見ておく形になります。上限に達すると生成はそこで止まるので、stop_reason の確認は欠かせません。

思考が長くなるリクエストには、別の注意もあります。思考が1リクエストあたり32kトークン前後を超える負荷では、システムのタイムアウトや接続数の上限に当たりうるため、バッチ処理を使うよう案内されています。30万トークン出力はもともとバッチ専用なので、この点では相性が良い設計です。

1時間超の生成を24時間枠に収める設計

30万トークンの1回の生成は、1時間を超えることがあります。バッチ全体の処理枠は24時間です。この2つの数字から、設計上の論点が3つ出てきます。

通常の「大半は1時間以内」は当てにならない

バッチAPIの案内では、ほとんどのバッチが1時間未満で終わるとされています。しかし拡張出力の1リクエストは、生成そのものに1時間超かかりえます。

このため、状態確認の間隔を短くしても完了は早まりません。数分おきの取得を繰り返すより、標準バッチより長い待ち時間を見込んで、間隔を広く取るほうが無駄な呼び出しを減らせます。

24時間で終わらなければ期限切れになる

バッチは24時間以内に処理が完了しないと失効します。混雑や自分のリクエスト量で処理が遅くなると、失効するリクエストが増えます。結果のステータスは succeeded / errored / canceled / expired の4種類なので、expired を再投入する処理を組んでおきます。

結果は作成から29日で取れなくなる

起点は処理終了時刻ではなく、バッチの created_at です。長時間かかる分、受け取りを後回しにしすぎないようにします。

投入後の実務は、次の流れになります。

1. 各リクエストに、内容が分かる一意の custom_id を付ける(結果の順序は保証されない)
2. バッチの状態を定期的に確認し、終了後に結果ファイルを取得する
3. expired と errored を抜き出して再投入する
4. 出力の末尾に到達しているかを stop_reason で確認する

一度投入したバッチは変更できません。プロンプトを直したい場合は、キャンセルして新しく投入します。キャンセルもすぐには反映されない場合があります。

料金は標準バッチ、上限まで使うといくらか

追加料金はありません。全利用が標準API価格の50%で、入力・出力・特殊トークンのすべてに適用されます。

出力を上限の300,000トークンまで使い切った場合の、出力ぶんだけの費用を計算しました。バッチ出力単価(100万トークンあたり)に0.3を掛けています。

入力トークンの費用は含みません。実際には途中で生成が終われば、その分だけ安くなります。

入力まで含めた1リクエストの概算も出しておきます。入力が5万トークン、出力が上限の30万トークンとします。式は「入力トークン数 × バッチ入力単価 + 出力トークン数 × バッチ出力単価」です。

出力の比重が圧倒的に大きいので、費用を左右するのは入力の長さより実際に生成される出力量です。思考トークンも出力として課金されるため、思考を深くするほど出力側の費用が伸びます。

共通の長い指示を入れる場合は、プロンプトキャッシュも併用できます。ただしバッチは並列・順不同に処理されるため、キャッシュヒットはベストエフォートです。バッチは5分を超えて処理されることがあるので、1時間キャッシュの利用が勧められています。

300kを使うべきか、分割するべきか

出力が長いほど、途中で拒否や停止が起きたときの損失も大きくなります。1リクエストの生成に1時間以上かかり、失敗すれば全体をやり直す構成は、再投入のコストが膨らみます。

判断材料は次のとおりです。

「章ごとに独立」なら、リクエストを分けたほうが並列で処理され、1件の失敗の影響も局所化されます。バッチでは、1件の失敗が他のリクエストの処理に影響しません。

出力量が読めないときの考え方は、入力サイズ不明でも最大出力を引き出す実装パターンにまとまっています。バッチでは拒否が成功として返る点にも注意が必要です。長い生成ほど見落としの損失が大きくなるので、Batch APIの拒否の落とし穴の判定条件も併せて実装します。

つまずきやすい点

バッチ全般の制約は、拡張出力にもそのまま当てはまります。

• stream: true は使えません。結果は1つのファイルで返ります
• speed(Fast mode)は使えません。同期のレイテンシ向けの機能です
• max_tokens: 0 は使えません。バッチ内の各リクエストは max_tokens が1以上必要です
• 1バッチは10万リクエストか256MBのどちらか早いほうまでです。超えると413の request_too_large になります
• リクエストごとに custom_id は一意でなければなりません

ヘッダーを付け忘れた場合や、対象外モデルに300000を指定した場合のエラー内容は、バッチ処理のドキュメントには書かれていません。本番投入の前に、1件だけの小さなバッチで試す方法があります。ベストプラクティスとしても、リクエストの形を同期のMessages APIで一度試し、検証エラーを避けることが挙げられています。

まとめ

30万トークン出力は、Message Batches APIとベータヘッダーの組み合わせでだけ使える枠です。対象はOpus 5.5から4.6までとSonnet 5.5・5・4.6の8モデルで、Fable系は入りません。Bedrock・Google Cloud・Foundryでは使えず、料金は標準バッチの50%です。

実装の難所は書き方でなく、運用側にあります。1回の生成が1時間を超えうること、24時間で失効すること、結果が29日で消えることを前提に、再投入と打ち切り検知を組みます。長文を1本で書かせる必要があるかどうかを先に決めると、分割という選択肢も自然に見えてきます。