Geminiでコンテキストキャッシングを活用してコストを95%削減する方法

Gemini 4 Neon は、繰り返し使われるプロンプトのプレフィックスを自動的にキャッシュし、通常の $3 ではなく $0.15/100万トークンで課金します。この記事では、キャッシュヒットを得られるプロンプトの配置方法、エージェントループで変わる点、そして usage.total_cached_tokens でヒットを確認する方法を解説します。

Ashley Goolam

Ashley Goolam

19 11月 2026

Geminiでコンテキストキャッシングを活用してコストを95%削減する方法

Apidog エンタープライズ

オンプレミスデプロイ

SSO & RBAC

SOC 2 準拠

Apidog Enterpriseを見る

Gemini 4 Neon のコンテキストキャッシュは、暗黙的(implicit)のみです。キャッシュを自分で作成する必要はありません。Google が 4,096 トークン以上の繰り返しプロンプト接頭辞を自動的にキャッシュし、キャッシュされた入力トークンを $3 ではなく $0.15/100万トークンで課金します。つまり 95% の割引です。これを活かすには、各リクエストの安定した部分を先頭に置き、バイト単位で完全に同一に保ち、usage.total_cached_tokens でヒットを確認します。

以下では、キャッシュヒットのためのプロンプト構成、エージェントループのルール、キャッシュ済みトークン数の読み取り方、そしてコーディングエージェントに実行させるテストについて解説します。

Gemini 4 Neon のコンテキストキャッシュはどのように機能するのか?

Gemini 4 Neon のコンテキストキャッシュは、自動的なプレフィックスキャッシュです。新しいリクエストが直近のリクエストと同じトークンで始まり、その共通プレフィックスが 4,096 トークン以上ある場合、Google は繰り返し部分をキャッシュから提供し、キャッシュレートで課金します。有効化の設定は不要で、キャッシュオブジェクト、TTL、ストレージ料金などを管理する必要もありません。

Google は 2026 年 11 月 18 日に Neon をリリースしました(モデル ID は gemini-4-neon、詳しくは発表ポストを参照)。キャッシュに関する仕様は次の表のとおりです。

項目 Gemini 4 Neon
キャッシュ方式 暗黙的のみ、デフォルトで有効
明示的キャッシュ(cachedContents、caches.create) 非対応
キャッシュヒットの最小プレフィックス 4,096 トークン
標準入力 $3.00/100万トークン
キャッシュ済み入力(Standard) $0.15/100万トークン
キャッシュ済み入力(Batch および Flex) $0.075/100万トークン
キャッシュ済み入力(Priority) $0.27/100万トークン
ヒットの確認場所 usage.total_cached_tokens
無料枠 なし、有料プランのみ

割引率は全ティアで 95% です。$0.15 は $3 の 5%、$0.075 は $1.50 の 5%、$0.27 は $5.40 の 5% です。思考トークンを含む出力トークンは Standard で $15/100万トークンのまま変わりません。キャッシュの対象は入力のみです。

Gemini 4 Neon の暗黙的キャッシュと明示的キャッシュの違い

Gemini 2.5 や 3 で明示的キャッシュを使っていた場合、これがコードを壊す変更点です。Google の Neon 移行ノートには明確にこう書かれています。Gemini 4 Neon は「明示的キャッシュ(cachedContents および caches.create)をサポートしない」ため、「リクエストから cached_content フィールドを削除すべき」です。

キャッシュのドキュメントには、Interactions API は暗黙的キャッシュのみをサポートし、明示的キャッシュはどの Gemini 4 モデルでも利用できないと記載されています。明示的キャッシュは、対応している Gemini 3 および 2.5 モデルでは引き続き generateContent 経由で利用可能です。

移行時に必要な作業は次のとおりです。

  1. caches.create を呼び出してキャッシュ名を保存しているコードを削除する。
  2. すべてのリクエストボディから cached_content を削除する。
  3. 使わなくなったキャッシュストレージの料金を払い続けないようにする。
  4. 以前明示的にキャッシュしていたコンテンツが各リクエストの最上部に来るよう、プロンプトを再構成する。

ドキュメントを固定したり TTL を選んだりすることはできず、ヒットも保証されません。ただし、ヒットの確率は大幅に上げられます。

Gemini 4 Neon のキャッシュにヒットするプロンプト構成方法

キャッシュヒットには、長く同一のプレフィックスを短い間隔で再送することが必要です。Google のドキュメントは 2 つのヒントを示しています。大きくて共通のコンテンツをプロンプトの先頭に置くこと、そして類似したプレフィックスを持つリクエストを短時間のうちに送ることです。

2 つの Gemini 4 Neon リクエストが、システム指示・ツール定義・4,096 トークンを超えるドキュメントからなる同一の安定プレフィックスを共有し、キャッシュヒット部分は $0.15/100万トークンで課金され、その後に続く異なる新規質問は $3/100万トークンで課金される様子

すべてのリクエストを次の順序で構成してください。

  1. システム指示。 固定テキスト。タイムスタンプ、ユーザー名、リクエスト ID を含めない。
  2. ツールと関数の宣言。 毎回同じリスト、同じ順序、同じ説明にする。
  3. 共有ドキュメント。 コードベース、契約書、API 仕様、長いポリシーファイルなど。
  4. 変化する部分。 ユーザーの質問、最新のツール結果、今日の日付など。

キャッシュミスの最も一般的な原因は、先頭近くにある小さな動的な値です。Current time: 2026-11-19T09:14:02Z のような行がシステム指示に入っていると、呼び出しごとにプレフィックスが変わり、その後の部分は一切マッチしなくなります。ドキュメントの後、末尾に移動しましょう。

その他のプレフィックス破壊要因:ランダムな順序で構築されるツールリスト、異なる空白で再シリアライズされるドキュメント、順序が変わって返される検索結果チャンクなどです。

プレフィックスは 4,096 トークンを超えてください。2,000 トークンのシステムプロンプトだけでは対象になりませんが、長い共有ドキュメントと組み合わせれば、合計プレフィックスが条件を満たします。

Interactions API では、安定した指示を system_instruction に渡し、ドキュメントを input の先頭に置きます。

from google import genai

client = genai.Client()  # reads GEMINI_API_KEY

SYSTEM = open("review_rules.md").read()      # fixed text
CODEBASE = open("repo_snapshot.txt").read()  # ~200K tokens, unchanged

def ask(question: str):
    interaction = client.interactions.create(
        model="gemini-4-neon",
        system_instruction=SYSTEM,
        input=CODEBASE + "\n\nQuestion: " + question,
    )
    print("cached tokens:", interaction.usage.total_cached_tokens)
    return interaction

ask("Where do we validate JWT expiry?")
ask("Which handlers skip input validation?")

最初の呼び出しでキャッシュが作られます。2 回目の呼び出しでキャッシュ済みトークンが 0 と表示されたら、プレフィックスのどこかが変わっています。

暗黙的キャッシュは両方の会話モードで機能します。上記のようなステートレスな呼び出しも対象であり、previous_interaction_id で連結するステートフルなセッションも同様です。リクエスト形式の詳細については、Gemini 4 Neon API ガイドをご覧ください。

エージェントループにおけるキャッシュの仕組み:2,050 トークンのルール

エージェントループは、各ターンで履歴全体を再送するため、キャッシュの効果が最も大きい場所です。Gemini 4 モデルには知っておくべきルールが 1 つ追加されています。Google のキャッシュドキュメントによると、「Gemini は、新しいリクエストが少なくとも 2,050 トークンを追加する場合にのみ、以前のリクエスト全体をキャッシュする」のです。モデル出力、思考、関数結果はすべてこの合計にカウントされます。

ターンで追加されるトークンが 2,050 未満の場合、Gemini は前のリクエストの末尾 2,050 トークンを標準入力レートで再処理します。プレフィックスのそれ以前の部分は依然としてヒットできますが、その末尾部分は $3/100万トークンで課金されます。

Google によると、ほとんどのエージェントターンはこの閾値を超えます。問題になるのは、{"ok": true} を返すステータスチェックのような、小さなステップの多いチャatty なループです。ターンあたりのコストは小さいものの(2,050 トークン × $3/100万で約 $0.006)、数千回の短いターンでは積み重なります。ループが大量の小さな呼び出しを行う場合は、ロジックが許す範囲で小さなツール結果を 1 つのターンにまとめましょう。

Gemini 4 Neon のコンテキストキャッシュでどれだけ節約できるのか?

200,000 トークンのコードベースについて 20 の質問に答えるコードレビューアシスタントを考えてみましょう。各質問は 3,000 トークンを追加し、1,000 トークンの回答を受け取ります。ティアは Standard です。

キャッシュヒットなしの場合、各呼び出しのコストは:

最初の呼び出し後にキャッシュヒットする場合、2〜20 回目の呼び出しのコストは:

キャッシュなしの最初の呼び出し $0.624 を加えると、セッション全体で $1.65、約 87% の節約です。

Standard ティアで 200K トークンのコードベースに関する 20 の質問に答える Gemini 4 Neon セッションの棒グラフ:キャッシュヒットなしでは $12.48、最初の呼び出し後にキャッシュヒットすると $1.65

節約率が 95% 未満なのは、出力と新規入力には割引が適用されないためです。共通プレフィックスが全体に占める割合が大きいほど、入力コストは 95% の節約に近づきます。同じ処理を Batch で実行すれば、キャッシュレートはさらに半分の $0.075 になります。料金表と思考レベルのコストの詳細は、Gemini 4 Neon の料金をご覧ください。

レスポンス内の Gemini 4 Neon キャッシュ済みトークンの確認方法

毎回のレスポンスで usage.total_cached_tokens を読み取ってください。Google はこれを、キャッシュヒットしたトークン数を示すフィールドとして、Python SDK と JavaScript SDK の両方でドキュメント化しています。

curl と jq を使う場合:

curl -s "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json | jq '.usage'

呼び出しの価格を計算するには、キャッシュ済みトークンを $0.15/100万、残りの入力を $3、出力と思考を $15 で課金します。キャッシュ済みトークン数をリクエスト ID と併せて記録しておきましょう。全トラフィックで突然 0 に落ちた場合は、通常デプロイによってプレフィックスが変わったことを意味します。新しいツール、言い回しの変わったルール、システム指示に入り込んだタイムスタンプなどが原因です。

Apidog CLI でコーディングエージェントにキャッシュヒットをテストさせる

プレフィックスは日常のリファクタリングで壊れがちで、請求書が届くまで誰も気づきません。キャッシュチェックを、コーディングエージェントが保守し CI が実行する API テストにしましょう。

Apidog CLI を使うと、Claude Code、Codex、Cursor、OpenCode がターミナルから API テストを作成・実行できます。まず一度セットアップします。

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

次に、エージェントに次のプロンプトを 1 つ渡します。

In Apidog project <id>, create an environment for the Gemini API with a
GEMINI_API_KEY variable. Build a test scenario called "Neon cache hit" with two
steps that POST to /v1beta/interactions with model gemini-4-neon, using our
production system_instruction and the docs/context.md file as the start of
input, then two different questions. Assert HTTP 200 on both, and assert that
usage.total_cached_tokens on step 2 is greater than 4096. Run it and tell me
the cached token count.

エージェントは環境とシナリオを作成し、ペイロードを CLI のスキーマと照合して実行します。

apidog environment create gemini-api --project <id> --base-url https://generativelanguage.googleapis.com
apidog test-scenario create --project <id> --name "Neon cache hit"
apidog cli-schema get test-scenario-update
apidog cli-schema validate test-scenario-update --file scenario.json
apidog test-scenario update <scenarioId> --project <id> --file scenario.json
apidog run -t <scenarioId> --project <id> -e <envId> -r cli,json

来月、誰かがシステムプロンプトにタイムスタンプを追加したら、その変更が出荷される前にステップ 2 のアサーションが失敗します。Apidog CLI CI/CD ガイドに従って apidog run -t <scenarioId> --project <id> -e <envId> -r junit をパイプラインに組み込むか、Claude Code での Apidog CLI から始めましょう。各実行で実際に Neon を 2 回呼び出すため、上記のレートでは 1 回あたり数セントのコストです。Apidog の Free プランは最大 4 ユーザーまで利用できます。

各プロバイダーにおけるプレフィックスキャッシュの仕組みについては、プロンプトキャッシュとはをご覧ください。

FAQ

Gemini 4 Neon は明示的なコンテキストキャッシュに対応していますか? いいえ。Google の Neon ガイドによると、cachedContents や caches.create には対応しておらず、リクエストから cached_content を削除すべきとされています。Neon は暗黙的キャッシュのみを使用し、これはデフォルトで有効です。

Gemini 4 Neon でキャッシュヒットに必要な最小プロンプトサイズは? 共通プレフィックスで 4,096 トークンです。Gemini 4 Hydrogen、Argon、Carbon と同じ最小値です。Gemini 2.5 Flash および Pro は 2,048 です。

Gemini 4 Neon のキャッシュ割引率は? キャッシュ済み入力で 95% です。Standard は $3 から $0.15/100万トークン、Batch および Flex は $1.50 から $0.075、Priority は $5.40 から $0.27 に下がります。出力と思考トークンには割引はありません。

Gemini 4 Neon に特定のプロンプトをキャッシュさせることはできますか? いいえ。暗黙的キャッシュには有効化する設定も、選択できる TTL も、ヒットの保証もありません。各リクエストの先頭に長く同一のプレフィックスを置き、類似リクエストを短時間のうちに送ることで、ヒットの確率を上げられます。

リクエストがキャッシュにヒットしたかどうかはどうやって分かりますか? レスポンス内の usage.total_cached_tokens を確認してください。ゼロより大きい値であれば、その数の入力トークンがキャッシュレートで課金されたことを意味します。

キャッシュは previous_interaction_id でも機能しますか? はい。Google のドキュメントによると、暗黙的キャッシュは previous_interaction_id で連結するステートフルな会話でも、履歴全体を自分で送るステートレスな呼び出しでも機能します。

ApidogでAPIデザイン中心のアプローチを取る

APIの開発と利用をよりシンプルなことにする方法を発見できる