Token Counting（トークンカウンティング）とは？AnthropicのToken Counting APIで送信前にトークン数を数える仕組み・使い方を完全解説

Token Counting（トークンカウンティング）とは

Token Counting（トークンカウンティング）とは、LLM（大規模言語モデル）に送信するテキストや画像、ツール定義などの入力が、何トークンに換算されるかを事前に計測する仕組みのこと。Anthropic はこの目的専用の POST /v1/messages/count_tokens エンドポイントを公式に公開している。

身近な例えで言えば、宅配便を出す前に重さを量って送料を見積もるのと同じ。Claude APIは入力トークン数 × 単価で課金されるため、「この長い文書を渡したら一体いくらかかるのか」を送信前に知るのは、コスト管理の観点で実務上ほぼ必須になる。Token Counting APIはまさにその「事前計量器」の役割を担う。

Token Countingの読み方

Token Countingの仕組み

Token CountingはMessages APIと同じ入力スキーマを受け取り、内部のトークナイザーを使って入力をトークン列に変換し、その個数だけを返す軽量なエンドポイントとして実装されている。実際に推論モデルを動かさないため、課金は発生せず、応答も高速だ。ここが重要なポイントです。

トークンとは何か

トークンとは、LLMがテキストを処理する最小単位。英語では概ね1単語または1サブワード、日本語では1〜2文字程度に相当する。「Hello world」は約2トークン、「こんにちは世界」は約7〜10トークンになる。Anthropicモデルのトークナイザーは公開されていないため、正確な数を知るには公式APIが必要になる。

API仕様の概要

Token Counting APIのリクエストは、Messages API（/v1/messages）からmax_tokensを除いたものとほぼ同じ。レスポンスは input_tokens 1フィールドだけが返る非常にシンプルな構造になっている。

# リクエスト例（JSON）
{
  "model": "claude-sonnet-4-5",
  "system": "あなたは丁寧な日本語アシスタントです",
  "messages": [
    {"role": "user", "content": "こんにちは、日本語で挨拶してください"}
  ]
}

# レスポンス例
{
  "input_tokens": 38
}

背景: なぜAnthropicが専用APIを用意したのか

OpenAIにはオープンソースの tiktoken ライブラリがあり、ローカルでトークン計測ができる。一方Anthropicはトークナイザーを公開していないため、開発者は実際にAPIを叩いてみるまで正確なトークン数がわからない、という課題が長らくあった。2024年に Token Counting API が公式リリースされ、この問題が解決された。実務では、コスト試算ツールやLLMキャッシュ管理ツールでこのAPIが標準的に使われている。

Token Countingの使い方・実例

基本的な使い方（Quick Start）

# Python公式SDK
import anthropic
client = anthropic.Anthropic()

resp = client.messages.count_tokens(
    model="claude-sonnet-4-5",
    system="You are a helpful assistant",
    messages=[
        {"role": "user", "content": "Hello, world!"}
    ]
)
print(resp.input_tokens)  # 例: 18

cURLで直接叩く例

curl https://api.anthropic.com/v1/messages/count_tokens \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [
      {"role": "user", "content": "How many tokens is this?"}
    ]
  }'

よくある実装パターン

パターンA: 送信前のコスト見積もり

def estimate_cost(messages, input_price_per_mtok=3.0):
    # 入力トークン数から$コストを概算する
    resp = client.messages.count_tokens(
        model="claude-sonnet-4-5",
        messages=messages
    )
    cost_usd = resp.input_tokens / 1_000_000 * input_price_per_mtok
    return resp.input_tokens, cost_usd

向いているケース: 長文ドキュメントを送るバッチ処理、ユーザーがアップロードしたPDFのコスト警告表示。

避けるべきケース: チャットUIの入力欄でキー入力ごとに呼ぶような高頻度呼び出し（レート制限を簡単に超える）。

パターンB: コンテキストウィンドウ超過の事前検知

def safe_send(messages, max_context=200_000):
    count = client.messages.count_tokens(
        model="claude-sonnet-4-5",
        messages=messages
    ).input_tokens
    if count > max_context - 1024:
        raise ValueError(f"Context too long: {count} tokens")
    return client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=1024,
        messages=messages
    )

向いているケース: 動的に膨らむ会話履歴やツール出力を扱うエージェント。実行前に「入りきらない」と検知して履歴をトリミングできる。実務では、長時間動くエージェントワークフローで特に重要です。

避けるべきケース: max_tokensに余裕がある短い対話。オーバーヘッドのほうが大きくなる。

パターンC: クライアント側のキャッシュとセット

import hashlib, json
_cache = {}

def cached_count(payload):
    key = hashlib.sha256(json.dumps(payload, sort_keys=True).encode()).hexdigest()
    if key in _cache:
        return _cache[key]
    n = client.messages.count_tokens(**payload).input_tokens
    _cache[key] = n
    return n

向いているケース: 同じシステムプロンプトを複数ユーザーで使い回す場合や、ファインチューニング不要のRAGアプリ。

アンチパターン: 入力欄のonChangeで毎回呼ぶ

# ⛔ 絶対NG（レート制限超過＆無駄なネットワーク負荷。ここは特に注意してください）
input.addEventListener("input", async () => {
  const r = await fetch("/api/count", {...});
});

キー入力1回ごとにToken Counting APIを呼ぶと、すぐにRPM上限に達してアプリ全体がエラーになる。実務では、送信ボタン押下時、または500ms程度のデバウンス後に呼ぶこと。

Token Countingのメリット・デメリット

メリット

• API課金が発生する前にコストを見積もれる
• コンテキストウィンドウ超過を事前に検知できる
• tool_use、image、systemプロンプトを含む完全な入力で計測できる
• 無料で利用できる（レート制限内で）
• 応答が速い（推論を実行しないため）

デメリット・注意点

• output_tokens（出力側）は計測できない
• レート制限はあなたの利用ティアと共有される
• ±数トークン程度の誤差が出ることがある
• ローカルでオフライン計測する手段がない（Anthropicのトークナイザーが非公開のため）
• 呼びすぎるとレイテンシが累積する

Token CountingとTiktokenの違い

Token CountingはAnthropic用、TiktokenはOpenAI用。同じ「トークン数を数える」目的でも、提供形態と精度が大きく異なる。下記の比較表で整理する。

使い分けのポイントとして、Anthropicモデルでは Token Counting API以外に正確な手段はない、と覚えておきましょう。

Token Countingに関するよくある誤解

誤解1: 「Token CountingはMessages APIと同じく課金される」

なぜそう誤解されるのか: 多くのAPIエンドポイントが従量課金であるという背景から、Anthropicの全エンドポイントも課金されると思い込みやすい。実際、Anthropic公式ドキュメント上では「free」と明記されている部分を読み飛ばすケースが多いと考えられる。

正しい理解: Token Counting APIは無料。ただしレート制限はティアに紐づくため、無制限ではない。料金はかからないが、呼びすぎは別の意味で問題になる。

誤解2: 「Token Countingの結果と実際のbillingが完全一致する」

なぜそう誤解されるのか: 公式APIなのだから「請求と1トークンも違わないはず」と期待してしまうため。しかしAPI内部のメッセージフォーマットや改行処理で±数トークンの差が出ることがあり、Anthropicも完全一致を約束していない。Stack Overflow等でも実測との微差を報告するスレッドがしばしば確認される。

正しい理解: 見積もり精度として十分高いが、請求書とトークン単位で合わせる用途には使わない。月間予算管理にはAdmin Console上の使用量レポートを使うのが正確。

誤解3: 「output_tokensもToken Countingで予測できる」

なぜそう誤解されるのか: 「token counting」という命名が「全部のトークンを数える」という印象を与えるため。実務では、命名から機能を推測せず公式ドキュメントを確認することがポイントです、出力側も対象だと早合点しやすい。OpenAIにも出力カウンタがないにも関わらず、APIの命名上区別が見えにくい背景もある。

正しい理解: Token Counting APIは入力側のみ。出力トークンは生成してみないと確定しない。コスト上限を縛りたい場合はmax_tokensを指定するのが正攻法。

実務での活用シーン

1. ドキュメント検索アプリ（RAG）

RAG（Retrieval-Augmented Generation）では、検索でヒットしたチャンクをプロンプトに詰め込む。チャンク数が多すぎるとコンテキスト超過するため、Token Countingで合計トークン数を確認しながらチャンクを増減させる動的制御が一般的。

2. 長文要約サービス

ユーザーが大きな文書をアップロードしたとき、「この文書を要約すると約〇〇トークン、コストは$〇〇です」と事前に表示するUI。AnthropicのClaude Workbenchやサードパーティのコスト見積もりツールでも採用されている。

3. プロンプトキャッシュとの組み合わせ

Prompt Caching（プロンプトキャッシュ）は1024トークン以上のシステムプロンプトでないと有効にならない。Token Countingで「このシステムプロンプトはキャッシュ対象に十分か」を確認するのは実務でよく使われるパターン。

4. 社内のコスト監視ダッシュボード

各部署のClaude API利用量を可視化するBIダッシュボード。Token Countingを噛ませたAPIゲートウェイで全リクエストのトークン数を記録し、部署別の利用状況を集計する運用が増えている。

Token Countingに関するよくある質問（FAQ）

まとめ

• Token Counting（トークンカウンティング）はLLMの入力トークン数を事前に計測する仕組みで、Anthropicは公式に専用APIを提供している。
• エンドポイントは POST /v1/messages/count_tokens で、レスポンスは input_tokens のみ。
• Messages APIと同じ入力スキーマを受け取り、image・tool_use・systemプロンプトをすべて計測対象にできる。
• 無料で使えるが、レート制限はあなたのアカウントティアに従う。
• 出力トークン数は事前に分からないため、max_tokensで上限を縛る運用が基本。
• OpenAIのTiktokenはローカル計測可能だが、Anthropicモデルではこの公式APIが事実上唯一の正確な手段。
• RAG、長文要約、プロンプトキャッシュ判定、コスト監視ダッシュボードなど、本番運用で広く使われている。

参考文献・出典