Claude の拡張思考を使うと、実際に課金されるトークン数とレスポンスに表示されるトークン数が一致しません。この動作を正しく理解しておかないと、コスト見積もりが大きくずれます。

課金は「生の思考トークン」に対して発生する

Claude が思考を行う際、内部では完全な推論プロセスが生成されます。APIが返すのはその要約や省略版ですが、課金は生成された生の思考トークン全体に対して行われます。

表示形式の設定（displayフィールド）は課金に影響しません。

display の2つの設定

thinking パラメータの display フィールドで、思考コンテンツの返し方を選べます。

display の値 返ってくる内容 デフォルトのモデル
"summarized" 要約されたテキスト Opus 4.6 / Sonnet 4.6 以前
"omitted" thinking フィールドが空文字列 Opus 4.8 / 4.7 / Fable 5 / Mythos 5

omitted の主な利点はレイテンシの削減です。サーバーが thinking トークンのストリーミングをスキップするため、最初のテキストトークンまでの時間が短くなります。コスト削減の効果はありません。

omitted にしても、レスポンスには signature フィールドが含まれます。これは思考コンテンツの整合性を保証するために内部的に使われるフィールドで、マルチターン会話で次のリクエストに思考ブロックを含める際に必要です。

# display: "omitted" の設定例（TTFT を削減したい場合）
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "omitted"},
    messages=[{"role": "user", "content": "この微分方程式を解いてください。..."}],
)
# response.content には thinking ブロック（空文字列）とテキストブロックが返る

実際の思考トークン数を確認する

usage.output_tokens_details.thinking_tokens で確認できます。

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=[{"role": "user", "content": "素数は無限に存在しますか？"}],
)

print(response.usage.output_tokens_details.thinking_tokens)
# 例: 312

レスポンスの usage オブジェクトは次のような構造です。

{
  "usage": {
    "input_tokens": 25,
    "output_tokens": 348,
    "output_tokens_details": {
      "thinking_tokens": 312
    }
  }
}

この例では出力 348 トークンのうち 312 トークンが思考に使われています。テキスト出力は 36 トークンです（348 - 312）。output_tokens が正式な課金合計であり、output_tokens_details は可観測性のための内訳です。

思考トークンが多い場合、コスト試算は「通常の出力トークン単価 × 全 output_tokens」で行えます。モデルによって単価は異なりますが、thinking_tokens と text_tokens に異なる単価は設定されていません。

なぜ全文を見せないのか

公式ドキュメントによれば、悪用防止のためです。完全な推論プロセスが見えると、特定の悪用パターンに利用される可能性があるため、要約または省略の形で返す設計になっています。

まとめ

  • 課金は生の思考トークン全体に発生する（表示形式に関係なし）
  • display: "summarized" は要約テキストを返す（旧モデルのデフォルト）
  • display: "omitted" は空文字列を返す（最新モデルのデフォルト）。レイテンシ削減のみが利点
  • omitted でも signature フィールドは維持されるためマルチターンに影響しない
  • 実際の思考トークン数は usage.output_tokens_details.thinking_tokens で確認できる
  • output_tokens が正式な課金合計。output_tokens_details は可観測性のための内訳