一般的な AI ワークフローでは、同じ入力トークンをモデルに繰り返し渡すことがあります。Gemini API には、次の 2 つの異なるキャッシュ保存メカニズムが用意されています。
- 暗黙的キャッシュ保存（Gemini 2.5 モデルで自動的に有効になります。費用削減は保証されません）
- 明示的なキャッシュ保存（ほとんどのモデルで手動で有効にできます。コスト削減が保証されます）
明示的なキャッシュ保存は、コスト削減を保証したいが、開発者の作業が追加される場合に便利です。
暗黙的なキャッシュ保存
暗黙的キャッシュ保存は、すべての Gemini 2.5 モデルでデフォルトで有効になっています。リクエストがキャッシュにヒットした場合、費用削減は自動的に転送されます。この機能を有効にするために必要な操作はありません。この変更は 2025 年 5 月 8 日から有効になります。コンテキスト キャッシュ保存の最小入力トークン数は、2.5 Flash の場合は 1,024、2.5 Pro の場合は 4,096 です。
暗黙的なキャッシュ ヒットの可能性を高めるには:
- プロンプトの先頭に、大きくて一般的なコンテンツを配置してみてください。
- 類似したプレフィックスを含むリクエストを短時間で送信しようとしている
キャッシュ ヒットしたトークンの数は、レスポンス オブジェクトの usage_metadata フィールドで確認できます。
明示的なキャッシュ保存
Gemini API の明示的なキャッシュ保存機能を使用すると、コンテンツをモデルに 1 回渡して入力トークンをキャッシュに保存し、後続のリクエストでキャッシュに保存されたトークンを参照できます。一定の量を超えると、キャッシュに保存されたトークンを使用する方が、同じトークン コーパスを繰り返し渡すよりも費用が安くなります。
一連のトークンをキャッシュに保存するときに、トークンが自動的に削除されるまでのキャッシュの存続期間を選択できます。このキャッシュ保存期間は有効期間（TTL）と呼ばれます。設定しない場合、TTL はデフォルトで 1 時間になります。キャッシュ保存の費用は、入力トークンのサイズとトークンの存続期間によって異なります。
このセクションでは、クイックスタートで説明されているように、Gemini SDK がインストールされている（または curl がインストールされている）ことと、API キーが構成されていることを前提としています。
OpenAI ライブラリを使用した明示的なキャッシュ保存
OpenAI ライブラリを使用している場合は、extra_body の cached_content プロパティを使用して明示的なキャッシュ保存を有効にできます。
明示的なキャッシュ保存を使用する状況
コンテキスト キャッシュ保存は、初期コンテキストの実体部分が、短いリクエストで繰り返し参照されるシナリオに特に適しています。次のようなユースケースでは、コンテキスト キャッシュ保存の使用を検討してください。
- 広範なシステム指示を伴う chatbot
- 長時間の動画ファイルの繰り返し分析
- 大規模なドキュメント セットに対する繰り返しのクエリ
- 頻繁なコード リポジトリの分析やバグ修正
明示的なキャッシュ保存によるコスト削減
コンテキスト キャッシュ保存は、全体的な運用コストを削減するために設計された有料の機能です。ご請求は次の項目に基づいて行われます。
- キャッシュ トークン数: キャッシュに保存された入力トークンの数。後続のプロンプトに含まれる場合は、割引料金で請求されます。
- 保存期間: キャッシュに保存されたトークンの保存時間（TTL）。キャッシュに保存されたトークン数の TTL 期間に基づいて課金されます。TTL に最小値や最大値の制限はありません。
- その他の項目: 入力トークンや出力トークンがキャッシュされていない場合などは、別の料金が適用されます。
最新の料金の詳細については、Gemini API の料金ページをご覧ください。トークンをカウントする方法については、トークンガイドをご覧ください。
その他の考慮事項
コンテキスト キャッシュを使用する場合は、次の点に注意してください。
- コンテキスト キャッシュ保存の入力トークンの最小数は、2.5 Flash の場合は 1,024、2.5 Pro の場合は 2,048 です。最大値は、指定されたモデルの最大値と同じです。（トークンのカウントについて詳しくは、トークンガイドをご覧ください）。
- モデルは、キャッシュに保存されたトークンと通常の入力トークンを区別しません。キャッシュに保存されたコンテンツはプロンプトの接頭辞です。
- コンテキスト キャッシュには特別なレート制限や使用量上限はありません。
GenerateContentの標準レート制限が適用され、トークン上限にはキャッシュに保存されたトークンが含まれます。 - キャッシュに保存されたトークンの数は、キャッシュ サービスの作成、取得、リスト オペレーションの
usage_metadataと、キャッシュの使用時のGenerateContentで返されます。