取り組みの背景 — なぜトークン数の事前把握が重要なのか
Claude APIを使ったアプリケーション開発で、予想外のコスト増加に悩んだ経験はありませんか？ 大量の画像やPDFを含むリクエストを送信した後に「思ったよりトークンを消費していた」と気づくのは、開発者にとって大きなストレスです。
Anthropicはこの課題を解決するために、Token Counting エンドポイントを提供しています。このエンドポイントを使えば、メッセージを実際に送信する前にトークン消費量を正確に見積もることができ、コスト管理とコンテキストウィンドウの最適化に大きく役立ちます。
Token Counting エンドポイントの基本
エンドポイントの概要
Token Counting エンドポイントは、Messages APIと同じリクエスト構造を受け取り、入力トークン数を返す専用のAPIです。
主な特徴:
- 無料で利用可能: トークンカウントの実行自体に料金は発生しません
- 全モデル対応: Claude Opus 4.6、Sonnet 4.6、Haiku 4.5 など、全てのアクティブなモデルで利用できます
- マルチモーダル対応: テキスト、画像、PDF、ツール定義を含むリクエストのトークン数を事前に確認できます
- 独立したレート制限: メッセージ作成APIとは別のレート制限が適用されるため、カウント処理がAPI呼び出しの制限に影響しません
基本的な使い方
Python SDKを使った最もシンプルなトークンカウントの例を見てみましょう。
import anthropic
client = anthropic.Anthropic()
# メッセージのトークン数をカウント
response = client.messages.count_tokens(
model="claude-sonnet-4-6-20260320",
messages=[
{
"role": "user",
"content": "Claude APIのToken Countingについて教えてください。"
}
]
)
print(f"入力トークン数: {response.input_tokens}")
# 出力例: 入力トークン数: 28TypeScript SDKでも同様に利用できます。
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const response = await client.messages.countTokens({
model: "claude-sonnet-4-6-20260320",
messages: [
{
role: "user",
content: "Tell me about Claude API token counting.",
},
],
});
console.log(`Input tokens: ${response.input_tokens}`);
// 出力例: Input tokens: 22システムプロンプトとツールを含むトークンカウント
実際のアプリケーションでは、システムプロンプトやツール定義が入力トークンの大部分を占めることがあります。Token Counting エンドポイントはこれらも含めた正確なカウントを提供します。
import anthropic
client = anthropic.Anthropic()
# システムプロンプト + ツール定義 + メッセージのトークンカウント
response = client.messages.count_tokens(
model="claude-sonnet-4-6-20260320",
system="あなたは天気予報アシスタントです。ユーザーの質問に正確な天気情報で答えてください。",
tools=[
{
"name": "get_weather",
"description": "指定された都市の現在の天気情報を取得します",
"input_schema": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "天気を調べたい都市名"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "温度の単位"
}
},
"required": ["city"]
}
}
],
messages=[
{
"role": "user",
"content": "東京の今日の天気を教えてください。"
}
]
)
print(f"入力トークン数（システム+ツール+メッセージ）: {response.input_tokens}")
# 出力例: 入力トークン数（システム+ツール+メッセージ）: 384ツール定義が多いアプリケーションでは、ツールだけで数百〜数千トークンを消費することがあります。この事前確認により、不要なツールを削減してコストを抑える判断ができます。
画像・PDFを含むリクエストのトークンカウント
マルチモーダルなリクエストでは、画像やPDFのトークン消費量が予測しづらいため、事前カウントが特に重要です。
import anthropic
import base64
client = anthropic.Anthropic()
# 画像ファイルを読み込んでBase64エンコード
with open("screenshot.png", "rb") as f:
image_data = base64.standard_b64encode(f.read()).decode("utf-8")
response = client.messages.count_tokens(
model="claude-sonnet-4-6-20260320",
messages=[
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/png",
"data": image_data
}
},
{
"type": "text",
"text": "この画像の内容を説明してください。"
}
]
}
]
)
print(f"画像含む入力トークン数: {response.input_tokens}")
# 出力例: 画像含む入力トークン数: 1,584画像のトークン数は解像度によって大きく変動します。高解像度の画像は数千トークンになることもあるため、事前確認が欠かせません。
本番環境での実践パターン
パターン1: コンテキストウィンドウ管理
長い会話を維持するチャットボットでは、コンテキストウィンドウの上限に達する前に古いメッセージを削除する必要があります。Token Countingを使えば、この管理を正確に行えます。
import anthropic
client = anthropic.Anthropic()
MODEL = "claude-sonnet-4-6-20260320"
MAX_INPUT_TOKENS = 180_000 # 安全マージンを含めた上限
SYSTEM_PROMPT = "あなたは親切なカスタマーサポートアシスタントです。"
def manage_conversation(messages: list, new_message: dict) -> list:
"""コンテキストウィンドウを超えないよう会話履歴を管理する"""
candidate = messages + [new_message]
# 現在のトークン数をカウント
count_response = client.messages.count_tokens(
model=MODEL,
system=SYSTEM_PROMPT,
messages=candidate
)
# 上限を超えている場合、古いメッセージから削除
while count_response.input_tokens > MAX_INPUT_TOKENS and len(candidate) > 1:
# 最初のユーザー・アシスタントのペアを削除
candidate = candidate[2:]
count_response = client.messages.count_tokens(
model=MODEL,
system=SYSTEM_PROMPT,
messages=candidate
)
print(f"会話を短縮: {count_response.input_tokens} tokens")
return candidateパターン2: コスト見積もりダッシュボード
バッチ処理の前にコストを事前見積もりする仕組みを構築できます。
import anthropic
client = anthropic.Anthropic()
# モデルごとの入力トークン単価（per 1M tokens, USD）
PRICING = {
"claude-opus-4-6-20260205": 15.0,
"claude-sonnet-4-6-20260320": 3.0,
"claude-haiku-4-5-20251001": 0.80,
}
def estimate_batch_cost(
model: str,
tasks: list[dict],
system: str = ""
) -> dict:
"""バッチ処理のコストを事前見積もり"""
total_tokens = 0
for task in tasks:
response = client.messages.count_tokens(
model=model,
system=system,
messages=[{"role": "user", "content": task["content"]}]
)
total_tokens += response.input_tokens
price_per_token = PRICING.get(model, 3.0) / 1_000_000
estimated_cost = total_tokens * price_per_token
return {
"total_input_tokens": total_tokens,
"estimated_input_cost_usd": round(estimated_cost, 4),
"average_tokens_per_task": total_tokens // len(tasks),
"task_count": len(tasks)
}
# 使用例
tasks = [
{"content": "この製品レビューの感情分析をしてください: ..."},
{"content": "次の文章を要約してください: ..."},
{"content": "以下のコードのバグを見つけてください: ..."},
]
estimate = estimate_batch_cost("claude-sonnet-4-6-20260320", tasks)
print(f"合計入力トークン: {estimate['total_input_tokens']:,}")
print(f"推定入力コスト: ${estimate['estimated_input_cost_usd']}")
# 出力例:
# 合計入力トークン: 1,245
# 推定入力コスト: $0.0037パターン3: プロンプトキャッシュとの併用
プロンプトキャッシュを使用している場合、Token Countingでキャッシュヒット率の最適化に役立てることもできます。キャッシュブレークポイントの配置を検討する際に、各セクションのトークン数を事前に把握しておくと効果的です。
import anthropic
client = anthropic.Anthropic()
# キャッシュ対象のシステムプロンプトのトークン数を確認
large_system_prompt = "..." * 1000 # 大規模なシステムプロンプト
response = client.messages.count_tokens(
model="claude-sonnet-4-6-20260320",
system=large_system_prompt,
messages=[{"role": "user", "content": "テスト"}]
)
print(f"システムプロンプトを含む入力トークン: {response.input_tokens}")
# キャッシュの最小要件（1,024トークン）を満たしているか確認
if response.input_tokens >= 1024:
print("✅ プロンプトキャッシュの対象になります")
else:
print("⚠️ トークン数が不足しています。キャッシュには1,024トークン以上が必要です")まとめ — Token Countingで賢くコスト管理
Claude APIのToken Counting エンドポイントは、コスト最適化とコンテキスト管理の両面で欠かせないツールです。特に以下のシナリオで威力を発揮します。
- バッチ処理のコスト事前見積もり: 大量のリクエストを送る前にコストを把握し、予算オーバーを防ぐ
- チャットボットの会話管理: コンテキストウィンドウの使用状況をリアルタイムで監視し、適切なタイミングで古いメッセージを削除
- マルチモーダルリクエストの最適化: 画像やPDFのトークン消費を事前確認し、コンテンツの解像度やサイズを調整
無料で利用できるこのエンドポイントを活用して、APIコストの「見える化」を始めてみてはいかがでしょうか。まずは自分のアプリケーションで最もトークンを消費しているリクエストを特定するところから始めると、最も効果的な最適化ポイントが見えてきます。
より詳しいAPI利用ガイドはAPIクイックスタートを、レート制限の管理についてはレート制限のベストプラクティスをご参照ください。