Dans un workflow d'IA typique, vous pouvez transmettre les mêmes jetons d'entrée à un modèle à plusieurs reprises. L'API Gemini propose deux mécanismes de mise en cache différents :
- Mise en cache implicite (activée automatiquement sur les modèles Gemini 2.5 et versions ultérieures, sans garantie d'économies)
- Mise en cache explicite (peut être activée manuellement sur la plupart des modèles, avec garantie d'économies)
La mise en cache explicite est utile lorsque vous souhaitez garantir des économies, mais elle nécessite un travail de développement supplémentaire.
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 répercutons automatiquement les économies si votre requête atteint les caches. Vous n'avez rien à faire pour activer cette fonctionnalité. Le nombre minimal de jetons d'entrée pour la mise en cache de contexte est indiqué dans le tableau suivant pour chaque modèle :
| Modèle | Limite minimale de jetons |
|---|---|
| Aperçu de Gemini 3 Flash | 1024 |
| Aperçu de Gemini 3 Pro | 4096 |
| Gemini 2.0 Flash | 1024 |
| Gemini 2.5 Pro | 4096 |
Pour augmenter les chances d'atteindre un 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é mis en cache dans le champ usage_metadata de l'objet de réponse.
Mise en cache explicite
Grâce à la fonctionnalité de mise en cache explicite de l'API Gemini, vous pouvez transmettre du contenu au modèle une seule fois, mettre en cache les jetons d'entrée, puis faire référence aux jetons mis en cache pour les requêtes suivantes. Pour certains volumes, 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 pendant laquelle vous souhaitez que le cache existe avant que les jetons ne soient automatiquement supprimés. Cette durée de mise en cache est appelée durée de vie (TTL). Si aucune valeur n'est spécifiée, la valeur TTL est de 1 heure par défaut. Le coût de la mise en cache dépend de la taille du jeton 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 rapide.
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-flash-preview'
# 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-flash-preview"
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 et d'un fichier texte mis en cache.
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-flash-preview";
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-flash-preview"
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-flash-preview",
"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-flash-preview: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-flash-preview"
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 avec 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 une nouvelle valeur 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 la valeur 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 l'heure d'expiration, vous pouvez utiliser un objet datetime
ou une chaîne datetime au format ISO (dt.isoformat(), comme
2025-01-27T16:02:36.473528+00:00). Votre heure doit inclure un fuseau horaire
(datetime.utcnow() n'en ajoute pas,
datetime.now(datetime.timezone.utc) en ajoute un).
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 la valeur 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 la valeur 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 la valeur 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 est basée sur les 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 aucune limite 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 obtenir des informations à jour sur les tarifs, consultez la page 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 de contexte :
- Le nombre minimal de jetons d'entrée pour la mise en cache de contexte varie selon le modèle. Le nombre maximal est le même que celui 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 aucun tarif ni aucune limite d'utilisation spéciaux pour la mise en cache de 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 liste du service de mise en cache, ainsi que dansGenerateContentlors de l'utilisation du cache.