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