count_tokensで送信前にトークン数を数える方法とレート制限

count_tokensで何が分かるか

count_tokens は、メッセージをClaudeに送る前にトークン数を見積もるエンドポイントです。呼び出しは無料で、実際のメッセージ生成とは別枠のレート制限で動きます。レート制限に近づいているかの事前チェック、モデルごとのコスト比較、プロンプトを目標の長さに収める作業のいずれにも使えます。長いドキュメントを分割して送る処理を組んでいるなら、分割前に各チャンクのトークン数を確認しておくことで、コンテキストウィンドウを超えるリクエストを送信前に弾けます。

本チュートリアルでは、基本のテキストメッセージからツール・画像・thinking・PDFを含む複雑なリクエストまでのトークン数の数え方を実行コード付きで確認します。Start/Build/Scale各ティアのレート制限と、実装時につまずきやすい点も扱います。

前提条件

• Anthropic APIキー(platform.claude.com のConsole > Settings > API keysで取得)
• 現行の全アクティブモデルがcount_tokensに対応しています。モデルを限定して使える機能ではありません
• カウント結果は見積もりです。実際にメッセージを送信したときのinput tokenと、小さな幅でずれることがあります
• CLI経由でも呼び出せます(ant messages count-tokens)。curlやSDKを使わない検証にはこちらが手早く済みます

手順1: 基本のメッセージでトークン数を数える

/v1/messages/count_tokens に、実際のメッセージ作成と同じ形式のリクエストボディを投げます。返るのはinput_tokensの合計だけです。

curl https://api.anthropic.com/v1/messages/count_tokens \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-5",
    "system": "You are a scientist",
    "messages": [{"role": "user", "content": "Hello, Claude"}]
  }'

レスポンスは{"input_tokens": 14}のようにシンプルです。カウント対象はシステムプロンプトを含むリクエスト全体で、Anthropicがシステム最適化のために自動で足すトークンが混ざることもあります。この自動追加分は課金対象外で、実際に課金されるのは自分のコンテンツ分だけです。SDKを使う場合はPython・TypeScriptともmessages.count_tokens / messages.countTokensという専用メソッドが用意されています。

response = client.messages.count_tokens(
    model="claude-opus-5",
    system="You are a scientist",
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(response.json())

const response = await client.messages.countTokens({
  model: "claude-opus-5",
  system: "You are a scientist",
  messages: [{ role: "user", content: "Hello, Claude" }],
});
console.log(response);

手順2: 複雑なコンテンツのトークン数を数える

count_tokensは、ツール定義や画像、拡張思考(extended thinking)、PDFを含むリクエストもそのまま受け付けます。ただしコンテンツの種類ごとに、数え方の細部が違います。

thinkingブロックの扱いはモデルによって挙動が変わる点が特に見落としやすく、モデルを切り替えるたびに保持ルールを確認する必要があります。過去ターンのthinkingを保持しないモデルへ切り替えた直後は、count_tokensの見積もりが急に小さく出ることがありますが、これは不具合ではなく仕様どおりの挙動です。

サーバーツールを使う会話全体のトークン消費を正確に知りたい場合、count_tokensだけでは足りません。最初のサンプリング呼び出し分しか含まれないため、ツールが実行され結果が返ってきたあとの2回目以降の呼び出し分は、実際にメッセージを送信してレスポンスのusageフィールドを見るまで分かりません。設計段階のおおよその見積もりにはcount_tokens、実際に発生したコストの検証にはレスポンスのusage、と使い分けるのが安全です。

curl https://api.anthropic.com/v1/messages/count_tokens \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-5",
    "tools": [{
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "input_schema": {
        "type": "object",
        "properties": {"location": {"type": "string"}},
        "required": ["location"]
      }
    }],
    "messages": [{"role": "user", "content": "東京の天気は?"}]
  }'

手順3: 新トークナイザーのモデルでは数え直す

Claude 4.7以降のモデルは、それより前のモデルとトークナイザーそのものが違います。同じ入力文でも、旧モデルとの比較で見積もりが約30%多く出ます。増分は入力内容に応じて変わるため一律の比率ではありません。移行前に測ったトークン数を新モデルへそのまま流用すると、レート制限の見積もりもコンテキストウィンドウの残量計算も外れます。移行時は必ず切り替え先のmodel IDで数え直します。同じリクエストを移行前後の2つのモデルIDに投げてinput_tokensを見比べれば、自分のワークロードでの実際の増分をその場で確認できます。

対応ティアとレート制限

count_tokens自体は無料ですが、モデルごとの利用ティア(usage tier)に紐づく1分あたりのリクエスト数(RPM)制限が別途かかります。

ティアはメッセージ作成の履歴やアカウントの状態にもとづいて組織単位に自動で割り当てられ、自分で選ぶものではありません。新規組織や利用履歴が浅い組織は、この表より低い上限のEvaluationティアから始まり、利用実績が積み上がるにつれて自動で引き上がります。上限を上げたいときは、ConsoleのRate limitsページにある「Request rate limit increase」から申請します。

見落としやすいのが、count_tokensとメッセージ作成のレート制限が完全に独立している点です。count_tokensを大量に呼んでも、実際のメッセージ作成側のRPM・ITPM・OTPM枠は消費しません。逆にメッセージ作成側で429エラーに近づいていても、事前チェックとしてのcount_tokens呼び出しは別枠のまま動きます。429エラー自体への対処はClaude rate limit(レート制限)エラーの対処にまとめています。

Start・Build・Scaleの各ティアには、RPM制限とは別に月間の支出上限(spend cap)も設定されています。Startは月500ドル、Buildは月1,000ドル、Scaleは月200,000ドルが上限で、Billingページで確認・変更できます。Customティアには月間上限がなく、上限はアカウントチームとの個別合意で決まります。RPM制限をクリアしていても、この支出上限に達すればリクエストは止まるため、両方を別軸として把握しておく必要があります。

RPM制限そのものも、1分間の平均値としてではなく短い間隔で強制されることがあります。たとえば60RPMの枠は、実際には1秒あたり1リクエストとして運用されることがあり、短時間にリクエストが集中すると平均では枠内でも制限に触れます。APIはトークンバケットアルゴリズムを使っており、使っていない分の枠が継続的に補充される方式です。固定間隔でリセットされるわけではないため、バーストを避けて呼び出しを均していれば、同じ月間リクエスト数でも制限に触れにくくなります。

Message Batches APIを使う場合は、ここまでとは別枠のレート制限が存在します。バッチ用の独自RPM制限に加えて、処理待ちキューに同時に入れられるバッチリクエスト数の上限も設けられています。全モデル共通の1枠として管理される点も、モデルごとに分かれるMessages APIのレート制限とは違うところです。大量のPDFやドキュメントをまとめて処理する運用でバッチAPIを使うなら、この枠も個別に確認しておきます。

よくあるつまずき

プロンプトキャッシュ込みの見積もりだと思ってしまう

count_tokensのリクエストにcache_controlブロックを含めることはできますが、キャッシュのロジックそのものは適用されません。返る数値は、キャッシュを使わない場合の見積もりです。実際のキャッシュ効果を含めたコスト削減の考え方はPrompt Cachingを理解するを参照してください。

サーバーツールの往復分を見落とす

web_searchやcode_executionのようなサーバーツールを使うリクエストでは、count_tokensは最初のサンプリング呼び出し分しかカウントしません。ツールが実行されて結果がClaudeに返り、さらに応答が生成されるまでの往復分は、この見積もりに含まれていません。ツール利用全体の実コストは、Claudeのツール利用で増えるトークン数でモデル別に扱っています。

見積もりのズレを誤差でなく仕様変更と誤認する

見積もりは小さな幅でずれることを前提とした数値です。数トークン程度の差は正常な誤差の範囲で、Anthropic側のシステム最適化トークンの扱いが急に変わったわけでもありません。ズレが常に大きい、あるいは方向が一貫している場合は、モデルIDを取り違えていないか(旧トークナイザーのモデルで数えて新トークナイザーのモデルに送っていないか)を先に疑います。

大きな設計判断に使わず、送信直前チェックに使う

count_tokensは呼び出しごとに独立したAPIリクエストです。プロンプトを組み立てるたびに毎回呼ぶと、それだけでレート制限枠を消費します。1Mトークンコンテキストのような大きな入力を扱う設計段階では、Claude 1Mコンテキストの実務活用の目安を先に押さえておきます。そのうえでcount_tokensは、送信直前の最終チェックに使う運用が現実的です。

まとめ

count_tokensは、メッセージ作成と独立したレート制限で動く無料の見積もりエンドポイントです。基本のテキストだけでなく、ツール・画像・thinking・PDFを含むリクエストもそのまま渡せます。ただしサーバーツールの往復分やthinkingブロックの保持ルールはモデルによって挙動が変わるため、種類ごとの違いを踏まえて読む必要があります。Start・Build・Scaleの各ティアは組織の利用実績で自動的に割り当てられ、上限を上げたい場合はConsoleから申請します。RPM制限とは別に月間の支出上限も設定されているため、両方を分けて監視する必要があります。Claude 4.7以降のモデルへ移行する際は、トークナイザーの変更を踏まえて必ず切り替え先のモデルで数え直してください。