Cached Contents

Gérez des caches de contexte explicites (cachedContents) via le protocole natif Gemini : mettez activement en cache un large contexte sous forme d’objet, référencez-le entre les requêtes pour des hits déterministes et un coût réduit. OfoxAI est compatible avec le Google GenAI SDK.

Pour les cas d’usage, la différence avec le cache implicite et les bonnes pratiques, voir le guide Cache explicite Gemini. Cette page est la référence d’API au niveau des endpoints.

Endpoints


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 avec un champ cachedContent dans le corps :


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

Authentification

Utilisez le header x-goog-api-key :


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

Champs de la ressource

Principaux champs de la ressource CachedContent :

Champ	Type	Description
`name`	string (lecture seule)	Handle du cache, de la forme `cachedContents/{id}`, retourné à la création
`model`	string (requis, immuable)	Modèle auquel le cache est lié, par ex. `models/gemini-3.1-pro-preview`
`contents`	array	Contenu à mettre en cache (même structure que le `contents` de generateContent)
`systemInstruction`	object	Instruction system à mettre en cache (optionnel)
`tools`	array	Définitions d’outils à mettre en cache (optionnel)
`ttl`	string	Durée de vie, chaîne de secondes (par ex. `"600s"`) ; mutuellement exclusif avec `expireTime`
`expireTime`	string	Horodatage d’expiration (RFC 3339) ; mutuellement exclusif avec `ttl`
`displayName`	string (immuable)	Nom personnalisé (optionnel)
`usageMetadata.totalTokenCount`	integer	Nombre de tokens mis en cache (utilisé pour la facturation)

Plage de TTL prise en charge : minimum / par défaut 600s (10 minutes), maximum 3600s (1 heure).

Créer un cache

Python

create.py


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"},
)
 
cache = client.caches.create(
    model="google/gemini-3.1-pro-preview",
    config=types.CreateCachedContentConfig(
        contents=[open("knowledge_base.txt").read()],
        system_instruction="Tu réponds strictement d'après le document fourni.",
        ttl="600s",
        display_name="kb-v1",
    ),
)
 
print(cache.name)                          # cachedContents/xxxxxxxx
print(cache.usage_metadata.total_token_count)

TypeScript

create.ts


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 cache = await ai.caches.create({
  model: 'google/gemini-3.1-pro-preview',
  config: {
    contents: [fs.readFileSync('knowledge_base.txt', 'utf-8')],
    systemInstruction: "Tu réponds strictement d'après le document fourni.",
    ttl: '600s',
    displayName: 'kb-v1',
  },
})
 
console.log(cache.name) // cachedContents/xxxxxxxx
console.log(cache.usageMetadata?.totalTokenCount)

cURL

Terminal


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": "<large contexte à mettre en cache>" }] }
    ],
    "ttl": "600s"
  }'

Réponse


{
  "name": "cachedContents/xxxxxxxx",
  "model": "google/gemini-3.1-pro-preview",
  "createTime": "2026-06-26T08:00:00Z",
  "updateTime": "2026-06-26T08:00:00Z",
  "expireTime": "2026-06-26T08:10:00Z",
  "displayName": "kb-v1",
  "usageMetadata": {
    "totalTokenCount": 14407
  }
}

Consulter / Supprimer

La consultation et la suppression ne nécessitent pas model ; OfoxAI localise l’amont à partir du handle du cache.

Python

manage.py


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

TypeScript

manage.ts


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

cURL

Terminal


# Consulter une entrée
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"

Référencer un cache pour générer

Ajoutez un champ cachedContent au corps de generateContent pour référencer le cache ; contents ne porte que la nouvelle question de ce tour :

Python

use.py


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),
)
 
print(response.text)
print(response.usage_metadata.cached_content_token_count)  # tokens de cache touchés

TypeScript

use.ts


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 },
})
 
console.log(response.text)
console.log(response.usageMetadata?.cachedContentTokenCount) // tokens de cache touchés

cURL

Terminal


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.

Facturation

Étape	Formule
Création du cache	`totalTokenCount × tarif cache_write`
Hit sur référence	`cachedContentTokenCount × tarif cache_read` (environ 0,10x du prix d’entrée standard)
Nouveau contenu par référence	Nouveau prompt / sortie du tour facturé au tarif standard

Les tarifs unitaires cache_write / cache_read de chaque modèle figurent dans le catalogue de modèles .

OfoxAI répartit la charge entre plusieurs projets GCP, et les caches explicites sont region-scoped. OfoxAI verrouille automatiquement (hard-lock) les références sur l’amont qui a créé le cache, sans aucune dérive ; un handle de cache ne peut être référencé / consulté / supprimé que par l’API Key qui l’a créé (tout accès inter-comptes renvoie 403). Voir guide Cache explicite · Routage déterministe.

Cached Contents

Endpoints

Authentification

Champs de la ressource

Créer un cache

Python

TypeScript

cURL

Réponse

Consulter / Supprimer

Python

TypeScript

cURL

Référencer un cache pour générer

Python

TypeScript

cURL

Facturation

Documentation associée