Cache explicite Gemini (cachedContents)

Gemini propose deux types de cache :

• Cache implicite (automatique) — le modèle détecte et réutilise automatiquement les préfixes de prompt répétés, sans aucune configuration. C’est le comportement par défaut décrit dans Cache de prompts ; les hits sont « best-effort », et la moindre modification du préfixe peut provoquer un miss.
• Cache explicite (cette page) — vous créez activement un large contexte sous forme d’objet de cache, récupérez un handle cachedContents/{id}, puis le référencez dans les requêtes generateContent suivantes. Les hits sont déterministes : tant que le cache n’a pas expiré, une référence touche toujours.

Utilisez le cache explicite lorsque vous avez un large contexte stable, réutilisé de façon répétée (longs documents, bases de code, bases de connaissances, instructions system fixes) et que vous voulez un taux de hit contrôlable et une facturation prévisible.

Quand utiliser le cache explicite

Endpoints

OfoxAI fournit les endpoints cachedContents complets sous le protocole natif Gemini :

POST   https://api.ofox.ai/gemini/v1beta/cachedContents              # Créer
GET    https://api.ofox.ai/gemini/v1beta/cachedContents/{id}         # Consulter
DELETE https://api.ofox.ai/gemini/v1beta/cachedContents/{id}         # Supprimer

Pour référencer un cache lors de la génération, utilisez l’endpoint generateContent standard et ajoutez cachedContent au corps de la requête :

POST   https://api.ofox.ai/gemini/v1beta/models/{model}:generateContent

Authentification

Comme pour les autres endpoints Gemini, utilisez le header x-goog-api-key :

x-goog-api-key: <votre OFOXAI_API_KEY>

Workflow complet

Ce qui suit illustre un flux complet : créer le cache → référencer le cache pour générer → supprimer le cache.

1. Créer un cache

Placez le large contexte à réutiliser dans contents, et spécifiez model et ttl (durée de vie) :

from google import genai
from google.genai import types
 
client = genai.Client(
    api_key="<votre OFOXAI_API_KEY>",
    http_options={"api_version": "v1beta", "base_url": "https://api.ofox.ai/gemini"},
)
 
# Un document volumineux réutilisé de façon répétée (doit atteindre le seuil minimal de tokens)
LONG_DOCUMENT = open("knowledge_base.txt").read()
 
cache = client.caches.create(
    model="google/gemini-3.1-pro-preview",
    config=types.CreateCachedContentConfig(
        contents=[LONG_DOCUMENT],
        ttl="600s",  # le cache vit 10 minutes
    ),
)
 
print(cache.name)  # cachedContents/xxxxxxxx —— le handle pour les références ultérieures

import { GoogleGenAI } from '@google/genai'
import fs from 'node:fs'
 
const ai = new GoogleGenAI({
  apiKey: '<votre OFOXAI_API_KEY>',
  httpOptions: { apiVersion: 'v1beta', baseUrl: 'https://api.ofox.ai/gemini' },
})
 
const longDocument = fs.readFileSync('knowledge_base.txt', 'utf-8')
 
const cache = await ai.caches.create({
  model: 'google/gemini-3.1-pro-preview',
  config: {
    contents: [longDocument],
    ttl: '600s', // le cache vit 10 minutes
  },
})
 
console.log(cache.name) // cachedContents/xxxxxxxx —— le handle pour les références ultérieures

curl "https://api.ofox.ai/gemini/v1beta/cachedContents" \
  -H "x-goog-api-key: $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3.1-pro-preview",
    "contents": [
      { "role": "user", "parts": [{ "text": "<placez ici un large contexte à réutiliser>" }] }
    ],
    "ttl": "600s"
  }'

Le name retourné (de la forme cachedContents/xxxxxxxx) est le handle du cache. Conservez-le pour les références et la gestion ultérieures.

2. Référencer le cache pour générer

Référencez le handle du cache via cachedContent dans une requête generateContent ; contents ne contient que la nouvelle question de ce tour :

response = client.models.generate_content(
    model="google/gemini-3.1-pro-preview",
    contents="D'après le document ci-dessus, résume trois points clés",
    config=types.GenerateContentConfig(
        cached_content=cache.name,  # référencer le cache
    ),
)
 
print(response.text)
# Cache hit : la partie mise en cache est facturée au tarif « lecture » plus bas
print(response.usage_metadata.cached_content_token_count)

const response = await ai.models.generateContent({
  model: 'google/gemini-3.1-pro-preview',
  contents: "D'après le document ci-dessus, résume trois points clés",
  config: {
    cachedContent: cache.name, // référencer le cache
  },
})
 
console.log(response.text)
// Cache hit : la partie mise en cache est facturée au tarif « lecture » plus bas
console.log(response.usageMetadata?.cachedContentTokenCount)

curl "https://api.ofox.ai/gemini/v1beta/models/google/gemini-3.1-pro-preview:generateContent" \
  -H "x-goog-api-key: $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cachedContent": "cachedContents/xxxxxxxx",
    "contents": [
      { "role": "user", "parts": [{ "text": "D'\''après le document ci-dessus, résume trois points clés" }] }
    ]
  }'

En cas de hit, la réponse usageMetadata.cachedContentTokenCount indique le nombre de tokens issus du cache. Le même cache peut être référencé un nombre illimité de fois, chaque fois avec un hit déterministe, jusqu’à son expiration.

3. Consulter et supprimer

Consultez les métadonnées du cache, ou supprimez-le de façon proactive lorsqu’il n’est plus nécessaire (sans attendre l’expiration du TTL) :

# Consulter
info = client.caches.get(name=cache.name)
print(info.expire_time)
 
# Supprimer
client.caches.delete(name=cache.name)

// Consulter
const info = await ai.caches.get({ name: cache.name })
console.log(info.expireTime)
 
// Supprimer
await ai.caches.delete({ name: cache.name })

# Consulter
curl "https://api.ofox.ai/gemini/v1beta/cachedContents/xxxxxxxx" \
  -H "x-goog-api-key: $OFOX_API_KEY"
 
# Supprimer
curl -X DELETE "https://api.ofox.ai/gemini/v1beta/cachedContents/xxxxxxxx" \
  -H "x-goog-api-key: $OFOX_API_KEY"

Cycle de vie et TTL

À la création, spécifiez la durée de vie via ttl, sous forme de chaîne de secondes terminée par s (par ex. "600s").

• Pendant le TTL, le cache peut être référencé de façon répétée avec des hits déterministes.
• Après expiration du TTL, le cache est invalidé automatiquement, et le référencer renverra une erreur (le cache n’existe plus).
• Vous pouvez delete à tout moment pour le libérer plus tôt.

Facturation

Le cache explicite est facturé de façon transparente par token, en trois parties :

Amélioration OfoxAI : routage déterministe

OfoxAI répartit la charge entre plusieurs régions GCP / projets Vertex. Les caches explicites sont region-scoped (liés à une région) : un cache créé dans un projet GCP doit être référencé dans ce même projet, sinon vous obtenez un 404.

OfoxAI gère cela automatiquement : à la création, il enregistre l’instance amont à laquelle le cache est lié, puis retrouve cette instance via le handle du cache et verrouille les références sur le même amont (hard-lock). Que votre requête de référence porte ou non un identifiant user, quelle que soit la façon dont la charge est répartie, les références sont routées précisément vers le projet qui a créé le cache, sans aucune dérive. Vous n’avez pas à vous soucier de la répartition régionale sous-jacente.

Cache explicite vs cache implicite

Documentation associée

• Cache de prompts (cache implicite / vue d’ensemble inter-protocoles)
• API Gemini generateContent
• Catalogue de modèles et tarifs