Dans un workflow d'IA classique, vous pouvez transmettre les mêmes jetons d'entrée à un modèle de manière répétée. L'API Gemini propose deux mécanismes de mise en cache différents :
- Mise en cache implicite (activée automatiquement sur Gemini 2.5 et les modèles plus récents, sans garantie d'économies)
- Mise en cache explicite (peut être activée manuellement sur les modèles Gemini 3 et 2.5, garantie d'économies, non compatible avec Gemini 4 Argon et les versions ultérieures)
La mise en cache explicite est utile lorsque vous souhaitez garantir des économies, mais elle nécessite un travail supplémentaire de la part des développeurs.
Mise en cache implicite
La mise en cache implicite est activée par défaut pour tous les modèles Gemini 2.5 et versions ultérieures. Nous vous faisons automatiquement bénéficier d'économies si votre requête atteint les caches. Vous n'avez rien à configurer pour l'activer. Le tableau suivant indique le nombre minimal de jetons d'entrée pour chaque modèle :
| Modèle | Limite minimale de jetons |
|---|---|
| Gemini 4 Argon | 4 096 |
| Gemini 3.8 Flash | 4 096 |
| Gemini 3.6 Flash | 4 096 |
| Preview Gemini 3.1 Pro | 4 096 |
| Gemini 2.5 Flash | 2 048 |
| Gemini 2.5 Pro | 2 048 |
Pour augmenter les chances d'un succès de cache implicite :
- Essayez de placer les contenus volumineux et courants au début de votre requête
- Essayez d'envoyer des requêtes avec un préfixe similaire dans un court laps de temps
Vous pouvez voir le nombre de jetons qui ont été des succès de cache dans le champ usage_metadata de l'objet de réponse.
Mise en cache explicite
La fonctionnalité de mise en cache explicite de l'API Gemini vous permet de transmettre du contenu au modèle une seule fois, de mettre en cache les jetons d'entrée, puis de faire référence aux jetons mis en cache pour les requêtes suivantes. À partir d'un certain volume, l'utilisation de jetons mis en cache est moins coûteuse que la transmission répétée du même corpus de jetons.
Lorsque vous mettez en cache un ensemble de jetons, vous pouvez choisir la durée de conservation du cache avant la suppression automatique des jetons. Cette durée de mise en cache est appelée durée de vie (TTL). Si ce paramètre n'est pas défini, la valeur TTL par défaut est d'une heure. Le coût de la mise en cache dépend de la taille des jetons d'entrée et de la durée pendant laquelle vous souhaitez que les jetons soient conservés.
Cette section suppose que vous avez installé un SDK Gemini (ou que curl est installé) et que vous avez configuré une clé API, comme indiqué dans le guide de démarrage.
Générer du contenu à l'aide d'un cache
Python
L'exemple suivant montre comment générer du contenu à l'aide d'une instruction système et d'un fichier vidéo mis en cache.
Vidéos
import os
import pathlib
import requests
import time
from google import genai
from google.genai import types
client = genai.Client()
# Download a test video file and save it locally
url = 'https://storage.googleapis.com/generativeai-downloads/data/SherlockJr._10min.mp4'
path_to_video_file = pathlib.Path('SherlockJr._10min.mp4')
if not path_to_video_file.exists():
path_to_video_file.write_bytes(requests.get(url).content)
# Upload the video using the Files API
video_file = client.files.upload(file=path_to_video_file)
# Wait for the file to finish processing
while video_file.state.name == 'PROCESSING':
time.sleep(2.5)
video_file = client.files.get(name=video_file.name)
print(f'Video processing complete: {video_file.uri}')
model='models/gemini-3.8-flash'
# Create a cache with a 5 minute TTL (300 seconds)
cache = client.caches.create(
model=model,
config=types.CreateCachedContentConfig(
display_name='sherlock jr movie', # used to identify the cache
system_instruction=(
'You are an expert video analyzer, and your job is to answer '
'the user\'s query based on the video file you have access to.'
),
contents=[video_file],
ttl="300s",
)
)
response = client.models.generate_content(
model = model,
contents= (
'Introduce different characters in the movie by describing '
'their personality, looks, and names. Also list the timestamps '
'they were introduced for the first time.'),
config=types.GenerateContentConfig(cached_content=cache.name)
)
print(response.usage_metadata)
print(response.text)
from google import genai
from google.genai import types
import io
import httpx
client = genai.Client()
long_context_pdf_path = "https://sma.nasa.gov/SignificantIncidents/assets/a11_missionreport.pdf"
# Retrieve and upload the PDF using the File API
doc_io = io.BytesIO(httpx.get(long_context_pdf_path).content)
document = client.files.upload(
file=doc_io,
config=dict(mime_type='application/pdf')
)
model_name = "gemini-3.8-flash"
system_instruction = "You are an expert analyzing transcripts."
# Create a cached content object
cache = client.caches.create(
model=model_name,
config=types.CreateCachedContentConfig(
system_instruction=system_instruction,
contents=[document],
)
)
print(f'{cache=}')
response = client.models.generate_content(
model=model_name,
contents="Please summarize this transcript",
config=types.GenerateContentConfig(
cached_content=cache.name
))
print(f'{response.usage_metadata=}')
print('\n\n', response.text)
JavaScript
L'exemple suivant montre comment générer du contenu à l'aide d'une instruction système mise en cache et d'un fichier texte.
import {
GoogleGenAI,
createUserContent,
createPartFromUri,
} from "@google/genai";
const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });
async function main() {
const doc = await ai.files.upload({
file: "path/to/file.txt",
config: { mimeType: "text/plain" },
});
console.log("Uploaded file name:", doc.name);
const modelName = "gemini-3.8-flash";
const cache = await ai.caches.create({
model: modelName,
config: {
contents: createUserContent(createPartFromUri(doc.uri, doc.mimeType)),
systemInstruction: "You are an expert analyzing transcripts.",
},
});
console.log("Cache created:", cache);
const response = await ai.models.generateContent({
model: modelName,
contents: "Please summarize this transcript",
config: { cachedContent: cache.name },
});
console.log("Response text:", response.text);
}
await main();
Go
L'exemple suivant montre comment générer du contenu à l'aide d'un cache.
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
APIKey: "GOOGLE_API_KEY",
Backend: genai.BackendGeminiAPI,
})
if err != nil {
log.Fatal(err)
}
modelName := "gemini-3.8-flash"
document, err := client.Files.UploadFromPath(
ctx,
"media/a11.txt",
&genai.UploadFileConfig{
MIMEType: "text/plain",
},
)
if err != nil {
log.Fatal(err)
}
parts := []*genai.Part{
genai.NewPartFromURI(document.URI, document.MIMEType),
}
contents := []*genai.Content{
genai.NewContentFromParts(parts, genai.RoleUser),
}
cache, err := client.Caches.Create(ctx, modelName, &genai.CreateCachedContentConfig{
Contents: contents,
SystemInstruction: genai.NewContentFromText(
"You are an expert analyzing transcripts.", genai.RoleUser,
),
})
if err != nil {
log.Fatal(err)
}
fmt.Println("Cache created:")
fmt.Println(cache)
// Use the cache for generating content.
response, err := client.Models.GenerateContent(
ctx,
modelName,
genai.Text("Please summarize this transcript"),
&genai.GenerateContentConfig{
CachedContent: cache.Name,
},
)
if err != nil {
log.Fatal(err)
}
printResponse(response) // helper for printing response parts
}
REST
L'exemple suivant montre comment créer un cache, puis l'utiliser pour générer du contenu.
Vidéos
wget https://storage.googleapis.com/generativeai-downloads/data/a11.txt
echo '{
"model": "models/gemini-3.8-flash",
"contents":[
{
"parts":[
{
"inline_data": {
"mime_type":"text/plain",
"data": "'$(base64 $B64FLAGS a11.txt)'"
}
}
],
"role": "user"
}
],
"systemInstruction": {
"parts": [
{
"text": "You are an expert at analyzing transcripts."
}
]
},
"ttl": "300s"
}' > request.json
curl -X POST "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d @request.json \
> cache.json
CACHE_NAME=$(cat cache.json | grep '"name":' | cut -d '"' -f 4 | head -n 1)
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"contents": [
{
"parts":[{
"text": "Please summarize this transcript"
}],
"role": "user"
},
],
"cachedContent": "'$CACHE_NAME'"
}'
DOC_URL="https://sma.nasa.gov/SignificantIncidents/assets/a11_missionreport.pdf"
DISPLAY_NAME="A11_Mission_Report"
SYSTEM_INSTRUCTION="You are an expert at analyzing transcripts."
PROMPT="Please summarize this transcript"
MODEL="models/gemini-3.8-flash"
TTL="300s"
# Download the PDF
wget -O "${DISPLAY_NAME}.pdf" "${DOC_URL}"
MIME_TYPE=$(file -b --mime-type "${DISPLAY_NAME}.pdf")
NUM_BYTES=$(wc -c < "${DISPLAY_NAME}.pdf")
echo "MIME_TYPE: ${MIME_TYPE}"
echo "NUM_BYTES: ${NUM_BYTES}"
tmp_header_file=upload-header.tmp
# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files?key=${GOOGLE_API_KEY}" \
-D upload-header.tmp \
-H "X-Goog-Upload-Protocol: resumable" \
-H "X-Goog-Upload-Command: start" \
-H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
-H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
-H "Content-Type: application/json" \
-d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null
upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"
# Upload the actual bytes.
curl "${upload_url}" \
-H "Content-Length: ${NUM_BYTES}" \
-H "X-Goog-Upload-Offset: 0" \
-H "X-Goog-Upload-Command: upload, finalize" \
--data-binary "@${DISPLAY_NAME}.pdf" 2> /dev/null > file_info.json
file_uri=$(jq ".file.uri" file_info.json)
echo "file_uri: ${file_uri}"
# Clean up the downloaded PDF
rm "${DISPLAY_NAME}.pdf"
# Create the cached content request
echo '{
"model": "'$MODEL'",
"contents":[
{
"parts":[
{"file_data": {"mime_type": "'$MIME_TYPE'", "file_uri": '$file_uri'}}
],
"role": "user"
}
],
"system_instruction": {
"parts": [
{
"text": "'$SYSTEM_INSTRUCTION'"
}
],
"role": "system"
},
"ttl": "'$TTL'"
}' > request.json
# Send the cached content request
curl -X POST "${BASE_URL}/v1beta/cachedContents?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-d @request.json \
> cache.json
CACHE_NAME=$(cat cache.json | grep '"name":' | cut -d '"' -f 4 | head -n 1)
echo "CACHE_NAME: ${CACHE_NAME}"
# Send the generateContent request using the cached content
curl -X POST "${BASE_URL}/${MODEL}:generateContent?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"contents": [
{
"parts":[{
"text": "'$PROMPT'"
}],
"role": "user"
}
],
"cachedContent": "'$CACHE_NAME'"
}' > response.json
cat response.json
echo jq ".candidates[].content.parts[].text" response.json
Lister les caches
Il n'est pas possible de récupérer ni d'afficher le contenu mis en cache, mais vous pouvez récupérer les métadonnées du cache (name, model, display_name, usage_metadata, create_time, update_time et expire_time).
Python
Pour lister les métadonnées de tous les caches importés, utilisez CachedContent.list() :
for cache in client.caches.list():
print(cache)
Pour récupérer les métadonnées d'un objet de cache, si vous connaissez son nom, utilisez get :
client.caches.get(name=name)
JavaScript
Pour lister les métadonnées de tous les caches importés, utilisez GoogleGenAI.caches.list() :
console.log("My caches:");
const pager = await ai.caches.list({ config: { pageSize: 10 } });
let page = pager.page;
while (true) {
for (const c of page) {
console.log(" ", c.name);
}
if (!pager.hasNextPage()) break;
page = await pager.nextPage();
}
Go
L'exemple suivant liste tous les caches.
caches, err := client.Caches.All(ctx)
if err != nil {
log.Fatal(err)
}
fmt.Println("Listing all caches:")
for _, item := range caches {
fmt.Println(" ", item.Name)
}
L'exemple suivant liste les caches en utilisant une taille de page de 2.
page, err := client.Caches.List(ctx, &genai.ListCachedContentsConfig{PageSize: 2})
if err != nil {
log.Fatal(err)
}
pageIndex := 1
for {
fmt.Printf("Listing caches (page %d):\n", pageIndex)
for _, item := range page.Items {
fmt.Println(" ", item.Name)
}
if page.NextPageToken == "" {
break
}
page, err = page.Next(ctx)
if err == genai.ErrPageDone {
break
} else if err != nil {
return err
}
pageIndex++
}
REST
curl "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GEMINI_API_KEY"
Mettre à jour un cache
Vous pouvez définir un nouveau ttl ou expire_time pour un cache. Il n'est pas possible de modifier d'autres éléments du cache.
Python
L'exemple suivant montre comment mettre à jour le ttl d'un cache à l'aide de client.caches.update().
from google import genai
from google.genai import types
client.caches.update(
name = cache.name,
config = types.UpdateCachedContentConfig(
ttl='300s'
)
)
Pour définir le délai d'expiration, il accepte un objet datetime ou une chaîne de date/heure au format ISO (dt.isoformat(), comme 2025-01-27T16:02:36.473528+00:00). Votre heure doit inclure un fuseau horaire (datetime.utcnow() n'associe pas de fuseau horaire, datetime.now(datetime.timezone.utc) associe un fuseau horaire).
from google import genai
from google.genai import types
import datetime
# You must use a time zone-aware time.
in10min = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(minutes=10)
client.caches.update(
name = cache.name,
config = types.UpdateCachedContentConfig(
expire_time=in10min
)
)
JavaScript
L'exemple suivant montre comment mettre à jour le ttl d'un cache à l'aide de GoogleGenAI.caches.update().
const ttl = `${2 * 3600}s`; // 2 hours in seconds
const updatedCache = await ai.caches.update({
name: cache.name,
config: { ttl },
});
console.log("After update (TTL):", updatedCache);
Go
L'exemple suivant montre comment mettre à jour le TTL d'un cache.
// Update the TTL (2 hours).
cache, err = client.Caches.Update(ctx, cache.Name, &genai.UpdateCachedContentConfig{
TTL: 7200 * time.Second,
})
if err != nil {
log.Fatal(err)
}
fmt.Println("After update:")
fmt.Println(cache)
REST
L'exemple suivant montre comment mettre à jour le ttl d'un cache.
curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"ttl": "600s"}'
Supprimer un cache
Le service de mise en cache fournit une opération de suppression pour supprimer manuellement du contenu du cache. L'exemple suivant montre comment supprimer un cache :
Python
client.caches.delete(cache.name)
JavaScript
await ai.caches.delete({ name: cache.name });
Go
_, err = client.Caches.Delete(ctx, cache.Name, &genai.DeleteCachedContentConfig{})
if err != nil {
log.Fatal(err)
}
fmt.Println("Cache deleted:", cache.Name)
REST
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY"
Mise en cache explicite à l'aide de la bibliothèque OpenAI
Si vous utilisez une bibliothèque OpenAI, vous pouvez activer la mise en cache explicite à l'aide de la propriété cached_content sur extra_body.
Quand utiliser la mise en cache explicite ?
La mise en cache de contexte est particulièrement adaptée aux scénarios où un contexte initial important est référencé à plusieurs reprises par des requêtes plus courtes. Envisagez d'utiliser la mise en cache de contexte pour les cas d'utilisation suivants :
- Chatbots avec des instructions système détaillées
- Analyse répétitive de fichiers vidéo longs
- Requêtes récurrentes sur des ensembles de documents volumineux
- Analyse fréquente du dépôt de code ou correction de bugs
Comment la mise en cache explicite réduit les coûts
La mise en cache de contexte est une fonctionnalité payante conçue pour réduire les coûts. La facturation dépend des facteurs suivants :
- Nombre de jetons mis en cache : nombre de jetons d'entrée mis en cache, facturés à un tarif réduit lorsqu'ils sont inclus dans les requêtes suivantes.
- Durée de stockage : durée pendant laquelle les jetons mis en cache sont stockés (TTL), facturée en fonction de la durée TTL du nombre de jetons mis en cache. Il n'existe pas de limites minimale ou maximale pour la valeur TTL.
- Autres facteurs : d'autres frais s'appliquent, par exemple pour les jetons d'entrée et de sortie non mis en cache.
Pour en savoir plus sur les tarifs, consultez la page des tarifs de l'API Gemini. Pour savoir comment compter les jetons, consultez le guide sur les jetons.
Informations complémentaires
Tenez compte des points suivants lorsque vous utilisez la mise en cache du contexte :
- Le nombre minimal de jetons d'entrée pour la mise en cache du contexte varie selon le modèle. La valeur maximale est identique à la valeur maximale du modèle donné. (Pour en savoir plus sur le comptage des jetons, consultez le guide sur les jetons).
- Le modèle ne fait aucune distinction entre les jetons mis en cache et les jetons d'entrée standards. Le contenu mis en cache est un préfixe de la requête.
- Il n'existe pas de limites de débit ou d'utilisation spécifiques pour la mise en cache du contexte. Les limites de débit standards pour
GenerateContents'appliquent, et les limites de jetons incluent les jetons mis en cache. - Le nombre de jetons mis en cache est renvoyé dans
usage_metadataà partir des opérations de création, d'obtention et de listage du service de cache, ainsi que dansGenerateContentlors de l'utilisation du cache.