# トークン事前カウントAPIで暴走コストを防ぐ設計

> Claude APIのcount_tokensエンドポイントは無料でトークン数を事前算出でき、レート制限超過を未然に防げる。Fable/Mythos系はトークナイザ変更で従来比約30%増える点に注意し、実装パターンを整理する。

- Canonical: https://kuucorp.com/blog/claude-token-counting-api-preflight-cost-design/
- Date: 2026-09-08
- Last modified: 2026-09-08
- Publisher: Kuu株式会社 (https://kuucorp.com)

---
大量のリクエストをバッチ投入したら想定外の429エラーで止まった、あるいは長文プロンプトがモデルのコンテキストウィンドウに収まらず切り詰められていた——こうした事故は、送信前にトークン数を把握していれば防げるものが多い。Claude APIにはメッセージを実際に作成せずトークン数だけを算出できる`count_tokens`エンドポイントが用意されている。

本記事では、このToken Counting APIの仕組みと、レート制限・コスト管理への組み込み方を整理する。

## Claude Token Counting APIとは何か

> `count_tokens`エンドポイントは無料でメッセージのトークン数を事前算出できる仕組みだ。

`POST /v1/messages/count_tokens`は、Messages APIと同じ構造化された入力（system・messages・tools・images・documents・thinking）を受け取り、実際に推論せず`input_tokens`の値だけを返す。利用に課金は発生せず、利用階層（Start/Build/Scale）ごとにそれぞれ5,000/10,000/20,000 RPMの専用レート制限が設定されている。この制限はMessages APIの消費枠とは独立しており、事前カウントを多用してもメッセージ作成側のレート制限は減らない。

## count_tokensは何を数え、何を数えないのか

> 画像・PDF・ツール定義・thinkingブロックは数えるが、キャッシュ済みトークンは数え方が異なる。

ツール定義・画像・PDF・extended thinkingのブロックはいずれもカウント対象になる。ただし細かい挙動には注意点がある。サーバーツール（Web検索やコード実行など）のトークン数は最初のサンプリング呼び出し分のみが対象になる。thinkingブロックは、モデルが前ターンのthinkingを保持する仕様であれば過去ターン分もカウントされ、保持しない仕様のモデルではAPI側で取り除かれカウントされない。またToken Counting APIはキャッシュロジックを使わずに見積もるため、リクエストに`cache_control`を含めても実際のキャッシュ効果は反映されない——プロンプトキャッシングの効果測定には使えない点は覚えておきたい。返る数値はあくまで推定値で、実際にメッセージを作成した際の入力トークン数と小さくずれることがある。Anthropicが自動付加するシステム最適化用トークンは課金対象外だ。

## なぜモデル移行時にトークン数を数え直すべきか

> Claude Opus 4.7以降で導入された新トークナイザは、同じ入力でも旧モデル比で約30%多くカウントする。

Claude Fable 5.1・Claude Mythos 5.1・Claude Fable 5・Claude Mythos 5は、Claude Opus 4.7で導入されたトークナイザを共有しており、同じプロンプトでもOpus 4.7より前のモデルに比べておよそ30%多いトークン数になる（増加率はコンテンツの種類によって変動する）。課金・コンテキストウィンドウ消費もこの新トークナイザのカウントに従う。旧モデルで計測したトークン数を移行後のコスト試算やコンテキスト適合判断にそのまま流用してはならず、移行先の`model` IDを指定して`count_tokens`を実行し、数え直す必要がある。長文脈設計の詳細は[長文脈モデルの活用設計](/blog/long-context-window-design-patterns/)も参照してほしい。

## レート制限・コスト管理にどう活かすか

> 送信前にcount_tokensでITPM消費量を見積もれば、429エラーやコンテキスト超過を未然に防げる。

実装パターンは大きく3つある。第一に、大量のバッチ送信やループ処理の直前に合計トークン数を見積もり、Messages APIのITPM（入力トークン/分）制限に対する消費割合を計算してスロットリングをかける。第二に、見積もったトークン数でコンテキストウィンドウの残量を判断し、超過しそうな会話履歴を要約・切り詰めてから送信する。第三に、モデルルーティングの判断材料にする——小さいプロンプトは廉価モデルへ、大きい・複雑なプロンプトは上位モデルへ振り分ける閾値として使う。バッチ処理でのコスト削減は[Batch API実装手順](/blog/claude-batch-api-cost-reduction-smb/)、部門別のコスト計装は[AI FinOps入門](/blog/ai-finops-token-cost-instrumentation/)を参照。Token Counting API自体は無料なので、これらのチェックをリクエストのたびに呼び出しても追加コストは発生しない。

### 規模別の留意点（SMB / エンタープライズ）

SMBでは、月次のAPI費用が想定を超えないよう、バッチ送信スクリプトの先頭に`count_tokens`での見積もりとしきい値チェックを1行加えるだけで、想定外の高額請求を早期に検知できる。エンタープライズでは、LLMゲートウェイやFinOpsパイプラインに事前カウントを組み込み、部門・チーム単位の予算枠に対してリクエスト送信前にブロックする仕組みへ発展させられる。組織横断のコスト統制・ゲートウェイ設計が必要な場合は[Kuuの高度化支援サービス（RDE）](https://kuucorp.com/services/rde/)が対応する。

トークンコスト管理や運用設計のご相談は[Kuuの運用管理サービス（AI Ops）](https://kuucorp.com/services/ai-ops/)からお問い合わせください。

## 参考

- [Token counting（公式ドキュメント）](https://platform.claude.com/docs/en/build-with-claude/token-counting)
- [Rate limits（公式ドキュメント）](https://platform.claude.com/docs/en/api/rate-limits)
- [Count tokens in a Message - API Reference（公式ドキュメント）](https://platform.claude.com/docs/en/api/messages-count-tokens)

## まとめ

Token Counting APIは無料かつMessages APIとは独立したレート制限を持つため、送信前チェックとして気軽に組み込める。特にClaude Opus 4.7以降のトークナイザ変更で数え方自体が変わっている点は、モデル移行時のコスト試算を誤らせやすい落とし穴だ。レート制限超過・コンテキスト超過・想定外コストのいずれも、送信前の1回の見積もりで防げる範囲は大きい。