Gemini API の count_tokens 推定と実課金トークン数がズレる5つの原因 — 個人開発者向け原因切り分けと再計算パターン

# tools/compare_token_count.py
# 目的: count_tokens の予測値と usage_metadata の実測値を1ファイルで突き合わせる
import os
from google import genai
from google.genai import types
 
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
MODEL = "gemini-2.5-flash"
 
def compare(prompt: str, system_instruction: str | None = None, tools: list | None = None):
    config = types.GenerateContentConfig(
        system_instruction=system_instruction,
        tools=tools,
    )
 
    # ① 事前推定（課金されない無料の Tokenizer 呼び出し）
    estimated = client.models.count_tokens(model=MODEL, contents=prompt).total_tokens
 
    # ② 実リクエスト
    res = client.models.generate_content(model=MODEL, contents=prompt, config=config)
    usage = res.usage_metadata
 
    print(f"prompt        : {prompt[:40]}...")
    print(f"count_tokens  : {estimated}")
    print(f"usage prompt  : {usage.prompt_token_count}")
    print(f"usage thoughts: {getattr(usage, 'thoughts_token_count', 0)}")
    print(f"usage output  : {usage.candidates_token_count}")
    print(f"usage TOTAL   : {usage.total_token_count}")
    print(f"diff (est→real): {usage.total_token_count - estimated:+d}")
 
compare("Gemini API のトークン課金についてかんたんに説明してください。")

# 思考トークンを抑えたい時の代表的なパラメータ
config = types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(
        thinking_budget=512,  # 思考トークンの上限を明示
        include_thoughts=False,  # 思考要約を返さない
    ),
)

# 検証コード: ツール定義が課金トークンを膨らませることを確認
def get_weather(location: str) -> str:
    """指定都市の現在の天気を返します"""
    return "sunny"
 
# ツールあり / なし で比較
for has_tools in [False, True]:
    cfg = types.GenerateContentConfig(tools=[get_weather] if has_tools else None)
    r = client.models.generate_content(
        model=MODEL,
        contents="今日は出かけても大丈夫？",
        config=cfg,
    )
    label = "with tools" if has_tools else "no tools"
    print(f"{label}: prompt_tokens={r.usage_metadata.prompt_token_count}")

# マルチモーダル入力のトークン推定
import pathlib
from google.genai import types
 
img = types.Part.from_bytes(
    data=pathlib.Path("./screenshot.png").read_bytes(),
    mime_type="image/png",
)
prompt_parts = [img, "この画面のエラー原因を3つ挙げてください。"]
 
est = client.models.count_tokens(model=MODEL, contents=prompt_parts).total_tokens
print(f"multimodal estimated: {est}")

# チャット履歴を含めた現実的な見積もり
history = [
    types.Content(role="user", parts=[types.Part.from_text("最初の質問")]),
    types.Content(role="model", parts=[types.Part.from_text("最初の回答")]),
    # ... ターンが伸びるほど課金トークンも伸びる
]
new_user_msg = types.Content(role="user", parts=[types.Part.from_text("追加の質問")])
contents = history + [new_user_msg]
 
est = client.models.count_tokens(model=MODEL, contents=contents).total_tokens
print(f"with history: {est}")

# 課金額の正確な見積もり関数（料金は常に最新の公式ページで確認してください）
PRICE_INPUT = 0.30 / 1_000_000        # 例: $0.30 / 1M tokens
PRICE_CACHED_INPUT = 0.075 / 1_000_000 # 例: $0.075 / 1M tokens
PRICE_OUTPUT = 2.50 / 1_000_000        # 例: $2.50 / 1M tokens
PRICE_THOUGHTS = 2.50 / 1_000_000      # Thinking モデルは output と同単価
 
def estimate_cost(usage) -> float:
    cached = getattr(usage, "cached_content_token_count", 0) or 0
    fresh_input = usage.prompt_token_count - cached
    thoughts = getattr(usage, "thoughts_token_count", 0) or 0
    output = usage.candidates_token_count
    return (
        fresh_input * PRICE_INPUT
        + cached * PRICE_CACHED_INPUT
        + output * PRICE_OUTPUT
        + thoughts * PRICE_THOUGHTS
    )

# tools/realistic_estimate.py
# 目的: 本番と同じ条件で count_tokens し、5要因を補正したコストを出す
from dataclasses import dataclass
 
@dataclass
class CostEstimate:
    prompt_tokens: int
    expected_output: int
    expected_thoughts: int
    cached_tokens: int
 
    def total_cost(self) -> float:
        fresh = self.prompt_tokens - self.cached_tokens
        return (
            fresh * PRICE_INPUT
            + self.cached_tokens * PRICE_CACHED_INPUT
            + self.expected_output * PRICE_OUTPUT
            + self.expected_thoughts * PRICE_THOUGHTS
        )
 
# 使用例
prompt_tokens = client.models.count_tokens(
    model=MODEL,
    contents=full_contents_with_history_and_tools_and_media,
).total_tokens
 
estimate = CostEstimate(
    prompt_tokens=prompt_tokens,
    expected_output=400,    # 過去ログから 95 パーセンタイル
    expected_thoughts=600,  # Thinking モデルなら計測値を入れる
    cached_tokens=0,         # キャッシュ使用時のみ加算
)
print(f"per request: ${estimate.total_cost():.6f}")