◉GEMINI LABEN
●OMNI 1.2 — Gemini Omni 1.2 Flash が GA になりました(11/5)。最長15秒の動画生成と会話での編集に対応し、1.1 Flash は 12/3 に自動で 1.2 へ振り替わります●COMPUTER — Computer Use が Interactions / GenerateContent API で GA になりました(10/30)●LIVE — Live と TTS のプレビュー版は最短 11/17 に停止します(残り7日)。移行先は gemini-3.8-live と 3.8 系 TTS です●CLI — Gemini API CLI(gemini-api)がベータで登場(10/27)。エージェントやCI向けのゼロ依存クライアントです●2.5 PRO — gemini-2.5-pro と 2.5-flash は 12/1 から自動で振り替えられます(残り21日)。移行先は 3.8 Flash と 3.5 Flash-Lite です●NEW — クラッシュ報告を毎回ゼロから読ませない — 既知バグ早見表を先に grep し…●OMNI 1.2 — Gemini Omni 1.2 Flash が GA になりました(11/5)。最長15秒の動画生成と会話での編集に対応し、1.1 Flash は 12/3 に自動で 1.2 へ振り替わります●COMPUTER — Computer Use が Interactions / GenerateContent API で GA になりました(10/30)●LIVE — Live と TTS のプレビュー版は最短 11/17 に停止します(残り7日)。移行先は gemini-3.8-live と 3.8 系 TTS です●CLI — Gemini API CLI(gemini-api)がベータで登場(10/27)。エージェントやCI向けのゼロ依存クライアントです●2.5 PRO — gemini-2.5-pro と 2.5-flash は 12/1 から自動で振り替えられます(残り21日)。移行先は 3.8 Flash と 3.5 Flash-Lite です●NEW — クラッシュ報告を毎回ゼロから読ませない — 既知バグ早見表を先に grep し…
記事一覧/API / SDK
◈ API / SDK/2026-06-21上級

Gemini API の usageMetadata で本番アプリのコストを記録する — リクエスト単位で請求書と突き合わせる実装パターン

usageMetadata をリクエスト単位で記録し、エンドポイント・ユーザー・モデル別にコストを按分する実装パターンに加え、3.5 Flash GA で既定モデルが差し替わってもコスト記録が狂わないよう resp.model_version を基点にした単価引き当てと、ドリフト・未知モデルを毎晩監査する仕組みまで解説します。

gemini-api293コスト管理18usageMetadata本番運用49python112billing3

✦ プレミアム記事

「先月の Google Cloud の請求書を開いたら、Gemini API の項目だけ予想の倍だった」— 個人開発で Gemini API を使い始めて半年ほどが経った頃、私はこの体験をしました。原因を調べようと管理コンソールを掘り下げても、リクエスト単位の内訳までは出てきません。結局はアプリ側で usageMetadata を記録していなかったことが、再発防止できない最大の理由でした。

usageMetadata は Gemini API のレスポンスに常に含まれている地味なフィールドですが、これを 1 リクエストずつ保存しておくだけで、後から「どのエンドポイント」「どのユーザー」「どのモデル」が請求の何割を占めているのか、ほぼ完璧に再現できます。ここでは私が個人プロジェクトで実際に運用している記録パターンと、Google Cloud の請求書と突き合わせる方法を共有します。

usageMetadata に含まれるフィールドを正確に把握する

最初につまずくのは、usageMetadata のフィールドが思った以上に多いことです。Python SDK(google-genai)でレスポンスを print するとこのような構造になっています。

from google import genai
 
client = genai.Client(api_key="YOUR_API_KEY")
resp = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Gemini API のコスト管理について200字で教えてください",
)
 
print(resp.usage_metadata)
# UsageMetadata(
#   prompt_token_count=18,
#   candidates_token_count=210,
#   cached_content_token_count=0,
#   thoughts_token_count=0,
#   tool_use_prompt_token_count=0,
#   total_token_count=228
# )

それぞれの意味は次の通りです。

  • prompt_token_count — 入力プロンプト全体のトークン数。System Instructions や履歴も含む
  • cached_content_token_count — Context Caching を使ったときにキャッシュから読み込んだトークン数(通常入力の 25% 程度の単価)
  • candidates_token_count — モデルが生成した出力トークン数。candidate_count が 2 以上なら全候補の合計
  • thoughts_token_count — Gemini 2.5 系の Thinking 出力トークン数。料金は出力トークンと同じ単価で課金される
  • tool_use_prompt_token_count — Function Calling や Code Execution の内部処理で消費した入力トークン
  • total_token_count — 上記すべての合計

ここで重要なのは「total_token_count を見るだけでは料金は計算できない」という事実です。同じ 1,000 トークンでも、入力・出力・キャッシュ済み・思考でそれぞれ単価が違うため、フィールドごとに分けて記録しないと請求書と一致しません。

1 リクエストずつ JSON ログに残す

私が運用している方法はシンプルで、API 呼び出しのラッパー関数で usageMetadata を JSONL ファイルに追記するだけです。「あとで集計するから今は保存しておく」という割り切りが、月末になって最も助かります。

import json
import time
from pathlib import Path
from google import genai
 
LOG_PATH = Path("logs/gemini_usage.jsonl")
LOG_PATH.parent.mkdir(exist_ok=True)
client = genai.Client(api_key="YOUR_API_KEY")
 
def call_gemini_logged(model: str, prompt: str, *, user_id: str, endpoint: str):
    """usageMetadata を必ず JSONL に追記してから返すラッパー"""
    started = time.time()
    resp = client.models.generate_content(model=model, contents=prompt)
    um = resp.usage_metadata
 
    record = {
        "ts": time.time(),
        "elapsed_ms": int((time.time() - started) * 1000),
        "user_id": user_id,
        "endpoint": endpoint,
        "model": model,
        "prompt": um.prompt_token_count,
        "cached": um.cached_content_token_count or 0,
        "candidates": um.candidates_token_count or 0,
        "thoughts": um.thoughts_token_count or 0,
        "tool_use": um.tool_use_prompt_token_count or 0,
        "total": um.total_token_count,
    }
    with LOG_PATH.open("a", encoding="utf-8") as f:
        f.write(json.dumps(record, ensure_ascii=False) + "\n")
 
    return resp
 
# 使用例
resp = call_gemini_logged(
    model="gemini-2.5-flash",
    prompt="今日の天気を一言で",
    user_id="u_001",
    endpoint="/api/weather/summary",
)
print(resp.text)

JSONL を選ぶ理由は 2 つあります。1 つは追記書き込みが原子的に近く、複数プロセスから書いてもログが壊れにくいこと。もう 1 つは、後で SQLite や DuckDB に取り込むのが read_json_auto() 一発で済むことです。

✦

ここまでお読みいただきありがとうございます。

この記事の続きを読む

この先には、実装コードやベンチマーク結果など、実務でお役に立てる内容をご用意しています。このサイトは広告を掲載しておらず、サーバーや開発にかかる費用はメンバーの皆様のご支援で成り立っています。もしお役に立てていましたら、ご支援いただけますと大変ありがたいです。

この記事で得られること
✦Gemini 3.5 Flash GA で既定モデルが動いても請求と一致し続けるよう、resp.model_version(実際に応答したモデル)を記録の基点にコスト集計を作り替える手順
✦単価表に無い model_version を例外で検知する監査ジョブ — 未知モデルを Pro 単価へ無言フォールバックさせない実装
✦要求と異なるモデルで応答された割合を毎晩可視化し、既定モデル切り替えを月末でなく当日に気づくドリフト監査
Stripe による安全な決済 · いつでもキャンセル可能
✦

この記事を購入する

この先の内容をすべてお読みいただけます。一度のご購入で、いつでも何度でもアクセスできます。このサイトは広告を掲載しておらず、皆さまのご支援がサーバー費用などの運営を支えています。

または
メンバーシップなら全記事が読み放題 →
シェア

お読みいただきありがとうございます

Gemini Lab は広告なしで運営しており、サーバー費用などの運営コストはメンバーシップのご支援で賄っています。実装コード・ベンチマーク・本番設計パターンなど、実務でお役立ていただける記事を毎日更新しています。もし読んでよかったと感じていただけましたら、ぜひご覧ください。

  • ✦コピー&ペーストで使える実装コード付き
  • ✦毎日新しい上級ガイドを追加
  • ✦¥580/月 または ¥1,480 の永久アクセス
メンバーシップを見る →

関連記事

◈ API / SDK2026-10-16
models は 200 なのに generateContent だけ 403 になる日 — 切り分けの順番を先に決めておく
モデル一覧の取得は 200 で通るのに、生成リクエストだけが 403 permission_denied で止まるときの切り分け手順です。キー・プロジェクト・請求の順に確かめる小さな診断スクリプトと、リトライしてはいけない理由、サポートへ渡す材料の揃え方をまとめました。
◈ API / SDK2026-07-15
自動採用された出力こそ抜き取る — 限られたレビュー予算で静かな品質劣化に気づく設計
信頼度ゲートが見ているのは、モデルが迷った出力だけです。静かな劣化は自動採用された側に沈みます。1日30分というレビュー予算を前提に、二項分布で検出日数を見積もり、層別抜き取りと累積監視で気づく速さを上げた設計と実測を共有します。
◈ API / SDK2026-10-22
gemini-4-argon へ model を替える前に、自分のコードから消すものを探します
gemini-4-argon への移行で、明示キャッシュ・temperature 系・小さな max_output_tokens・短いタイムアウトの 4 つが問題になりうることを、公式の移行チェックリストから整理しました。自分のリポジトリから該当行を探す標準ライブラリだけの小さなスクリプトと、替えた後の確認点、Flash を据え置く判断も添えています。