⚠️ この記事は開発者向けです。 Gemini API をプログラムから使う話で、コードを書く前提の内容です。 チャットとして使いたい方は、Geminiとは何か と Geminiの始め方 をご覧ください。そちらはコードを書きません。
長いマニュアルやコードベースに対して、Gemini API で何度も質問する。このとき毎回同じ資料を送り直していると、入力トークンのぶんだけ料金と待ち時間がかさみます。Gemini context cache（コンテキストキャッシュ）は、その「繰り返し送るぶん」を節約する仕組みです。この記事では、考え方・向くケース・使う流れの概略をやさしく整理します。
結論：同じ長い資料を使い回すなら効く
先に要点だけ言うと、コンテキストキャッシュがうれしいのは次の2点です。
- コストが下がる: 同じ長いコンテキストを繰り返し送るとき、キャッシュ済みのぶんは通常より安い料金で扱える
- レイテンシ（待ち時間）が下がる: 毎回フルで送り直さない設計にできるので、応答が返るまでの体感が軽くなりやすい
逆に言うと、「同じ長いコンテキストを何度も使う」場面でこそ効く機能です。1回きりの短いやりとりでは、ほとんどメリットがありません。まずはこの「向き不向き」を押さえるのが大事です。
前提として、トークンとコンテキスト長の基礎を知っているとスムーズです。まだの方はトークンとコンテキスト長を理解するを先に読むのがおすすめです。
仕組み：再送ぶんの「使い回し」だと考える
なぜ普通は割高になるのか
Gemini API では、料金もコンテキストウィンドウの消費も、送ったトークン数で効いてきます。チャット形式や反復Q&Aでは、毎回のリクエストに「長い資料＋今回の質問」がまるごと入ります。
たとえば、社内マニュアル全文（とても長い）に対して質問を10回繰り返すとします。何の工夫もなければ、マニュアル全文を10回送り直すことになり、そのたびに入力トークンの料金がかかります。
キャッシュは「一度置いておく棚」
コンテキストキャッシュは、この「毎回送り直している重たい部分」を一度サーバー側に置いておき、次回以降はそれを参照するイメージです。
図書館のたとえが分かりやすいかもしれません。分厚い参考書を毎回家から持ち込む（＝全文を再送する）かわりに、いったん図書館の棚に預けておき、来館するたびにその棚を指して使う。持ち運ぶ手間（再送のコストとレイテンシ）が減る、という発想です。
キャッシュなし（毎回フル送信）:
リクエスト1: [長い資料ぜんぶ] + [質問1]
リクエスト2: [長い資料ぜんぶ] + [質問2]
リクエスト3: [長い資料ぜんぶ] + [質問3]
^^^^^^^^^^^^^^^^^ 毎回フル課金・毎回フル送信
キャッシュあり（重い部分は使い回す）:
キャッシュ作成: [長い資料ぜんぶ] を一度だけ登録
リクエスト1: (キャッシュ参照) + [質問1]
リクエスト2: (キャッシュ参照) + [質問2] ← 再送ぶんが割引料金
リクエスト3: (キャッシュ参照) + [質問3]明示的キャッシュと暗黙的キャッシュ
Gemini のキャッシュには、大きく2つのタイプがあります。
- 暗黙的キャッシュ（implicit）: 対応モデルで自動的に働くもの。プロンプトの共通する前置き部分が繰り返されたときに、割引が自動で適用されることがある。開発者側の特別な操作は基本不要
- 明示的キャッシュ（explicit）: 開発者がキャッシュを自分で作成し、保持期間（TTL）を指定して使い回すもの。割引の扱いがより明確になる一方、作成・管理は自分で行う
どのモデルでどちらが使えるか、最小トークン要件、保存料金、TTL の既定値、呼び出すメソッド名などの細かい仕様は更新が速いです。判断が必要な場面では、必ず公式のコンテキストキャッシュのドキュメントで最新をご確認ください。
向くケース・向かないケース
機能の性質上、得意な場面とそうでない場面がはっきり分かれます。
| 向くケース | 向かないケース |
|---|---|
| 長いマニュアル・規程に対する反復Q&A | 毎回まったく違う短い入力を扱う |
| 大きなコードベースへの繰り返し質問 | 1回きりで終わるやりとり |
| 長いシステムインストラクションを毎回付ける | コンテキストが毎回大きく変わる |
| 同じ書類の束を何度も参照する | 同じ資料を使う回数がごく少ない |
ポイントは「同じ・長い・繰り返す」の3条件です。この3つがそろうほど、コンテキストキャッシュの効果が出やすくなります。
使う流れの概略
明示的キャッシュを使う場合、ざっくりとした流れは次のようになります（細部は SDK・モデルで変わるため、概念として捉えてください）。
- 使い回したい長いコンテキストを用意する: マニュアル全文や、対象のコードベースなど
- キャッシュを作成する: そのコンテキストと保持期間（TTL）を指定して、キャッシュを登録する
- キャッシュを参照してリクエストする: 以降の質問では、作成したキャッシュを指定しつつ、今回の質問だけを渡す
- 不要になったら破棄する/期限切れにまかせる: TTL が切れれば自動で消える。保持している間は保存料金がかかる場合があるので、使い終わったら整理する
暗黙的キャッシュの場合は、対応モデルであれば特別な操作なしに自動で効くことがあります。まずはそれに任せ、より確実に効かせたいときに明示的キャッシュを検討する、という順番が現実的です。
実際の API メソッド名・引数・対応モデルは公式ドキュメントが一次情報です。具体的な実装手順はコンテキストキャッシュの公式ガイドを参照してください。
コスト感の注意点
「キャッシュ＝とにかく安くなる」と思い込むと、かえって損をすることがあります。設計前に次の点を意識しておきましょう。
- 保存料金がかかる場合がある: キャッシュを保持している間、その容量・期間に応じた料金が発生することがあります。使い回す回数が少ないと、保存料金のほうが上回ることも
- 「割引」は再送ぶんに効く: 毎回の質問文そのものは通常どおり課金されます。安くなるのは「使い回している重い部分」です
- 最小トークン要件があることがある: ある程度の大きさのコンテキストでないとキャッシュ対象にならない場合があります
- 単価・要件は更新が速い: 具体的な料金・最小トークン・TTL の既定値などは断定せず、必ず公式で最新を確認する
実務での目安としては、「同じ長いコンテキストを、これから何回くらい使うか」を先に見積もることです。数回しか使わないなら無理にキャッシュせず、何十回・何百回と使い回すなら積極的に検討する、という判断が分かりやすいです。
料金の全体像についてはGemini API の料金と無料枠の考え方もあわせてご覧ください。
一次体験：効くのは「長文を何度も使う」場面
実際に長いコンテキストを反復利用する処理を組んでみると、コンテキストキャッシュが効くのは限られた条件だと体感します。社内の長い資料に対してQ&Aを何度も回すような用途では、毎回フル送信していたぶんが減り、コストと体感速度の両方が軽くなりました。
一方で、入力が毎回バラバラな処理に無理にキャッシュを挟むと、管理が増えるだけでメリットがほとんど出ません。「同じ長いものを繰り返し使うか」を先に見極めてから導入する。これが失敗しないコツだと感じています。
まとめ
- コンテキストキャッシュは、同じ長いコンテキストを繰り返し送るときの「再送ぶん」を節約する仕組み
- うれしいのはコスト削減とレイテンシ低減。ただし効くのは「同じ・長い・繰り返す」がそろう場面
- 暗黙的キャッシュ（対応モデルで自動）と明示的キャッシュ（自分で作成・TTL指定）の2タイプがある
- 流れは「長いコンテキストを用意 → キャッシュ作成 → 参照して質問 → 不要なら破棄」
- 保存料金がかかる場合があり、使い回す回数が少ないと逆に割高になることもある
- 対応モデル・最小トークン・料金・TTL・メソッド名などの細部は更新が速いため、必ず公式のキャッシュドキュメントで最新を確認する
トークンの数え方やコンテキスト長の基礎はトークンとコンテキスト長を理解するで、料金体系の全体像はGemini API の料金と無料枠の考え方で詳しく解説しています。これから API を触る方はGemini API 入門からどうぞ。