Repository Public
1In a typical AI workflow, you might pass the same input tokens over and over to2a model. The Gemini API offers two different caching mechanisms:34- Implicit caching (automatically enabled on Gemini 2.5 and newer models, no cost saving guarantee)5- Explicit caching (can be manually enabled on most models, cost saving guarantee)67Explicit caching is useful in cases where you want to guarantee cost savings,8but with some added developer work.910## Implicit caching1112Implicit caching is enabled by default for all Gemini 2.5 and newer models. We automatically13pass on cost savings if your request hits caches. There is nothing you need to do14in order to enable this. The minimum input15token count for context caching is listed in the following table for each model:1617| Model | Min token limit |18|---|---|19| Gemini 3.8 Flash | 4,096 |20| Gemini 3.7 Flash | 4,096 |21| Gemini 3.6 Flash | 4,096 |22| Gemini 3.5 Flash | 4,096 |23| Gemini 3.1 Pro Preview | 4,096 |24| Gemini 2.5 Flash | 2,048 |25| Gemini 2.5 Pro | 2,048 |2627To increase the chance of an implicit cache hit:2829- Try putting large and common contents at the beginning of your prompt30- Try to send requests with similar prefix in a short amount of time3132You can see the number of tokens which were cache hits in the response object's33`usage_metadata` field.3435## Explicit caching3637> [!WARNING]38> **Beta:** Explicit context caching is currently in Beta. Endpoints and SDK methods are available under `v1beta`.3940Using the Gemini API explicit caching feature, you can pass some content41to the model once, cache the input tokens, and then refer to the cached tokens42for subsequent requests. At certain volumes, using cached tokens is lower cost43than passing in the same corpus of tokens repeatedly.4445When you cache a set of tokens, you can choose how long you want the cache to46exist before the tokens are automatically deleted. This caching duration is47called the *time to live* (TTL). If not set, the TTL defaults to 1 hour. The48cost for caching depends on the input token size and how long you want the49tokens to persist.5051This section assumes that you've installed a Gemini SDK (or have curl installed)52and that you've configured an API key, as shown in the53[Get started guide](https://ai.google.dev/gemini-api/docs/generate-content/get-started).5455### Generate content using a cache5657### Python5859The following example shows how to generate content using a cached system60instruction and video file.6162### Videos6364 import os65 import pathlib66 import requests67 import time6869 from google import genai70 from google.genai import types7172 client = genai.Client()7374 # Download a test video file and save it locally75 url = 'https://storage.googleapis.com/generativeai-downloads/data/SherlockJr._10min.mp4'76 path_to_video_file = pathlib.Path('SherlockJr._10min.mp4')77 if not path_to_video_file.exists():78 path_to_video_file.write_bytes(requests.get(url).content)7980 # Upload the video using the Files API81 video_file = client.files.upload(file=path_to_video_file)8283 # Wait for the file to finish processing84 while video_file.state.name == 'PROCESSING':85 time.sleep(2.5)86 video_file = client.files.get(name=video_file.name)8788 print(f'Video processing complete: {video_file.uri}')8990 model='models/gemini-3.8-flash'9192 # Create a cache with a 5 minute TTL (300 seconds)93 cache = client.caches.create(94 model=model,95 config=types.CreateCachedContentConfig(96 display_name='sherlock jr movie', # used to identify the cache97 system_instruction=(98 'You are an expert video analyzer, and your job is to answer '99 'the user\'s query based on the video file you have access to.'100 ),101 contents=[video_file],102 ttl="300s",103 )104 )105106 response = client.models.generate_content(107 model = model,108 contents= (109 'Introduce different characters in the movie by describing '110 'their personality, looks, and names. Also list the timestamps '111 'they were introduced for the first time.'),112 config=types.GenerateContentConfig(cached_content=cache.name)113 )114115 print(response.usage_metadata)116117 print(response.text)118119### PDFs120121 from google import genai122 from google.genai import types123 import io124 import httpx125126 client = genai.Client()127128 long_context_pdf_path = "https://sma.nasa.gov/SignificantIncidents/assets/a11_missionreport.pdf"129130 # Retrieve and upload the PDF using the File API131 doc_io = io.BytesIO(httpx.get(long_context_pdf_path).content)132133 document = client.files.upload(134 file=doc_io,135 config=dict(mime_type='application/pdf')136 )137138 model_name = "gemini-3.8-flash"139 system_instruction = "You are an expert analyzing transcripts."140141 # Create a cached content object142 cache = client.caches.create(143 model=model_name,144 config=types.CreateCachedContentConfig(145 system_instruction=system_instruction,146 contents=[document],147 )148 )149150 print(f'{cache=}')151152 response = client.models.generate_content(153 model=model_name,154 contents="Please summarize this transcript",155 config=types.GenerateContentConfig(156 cached_content=cache.name157 ))158159 print(f'{response.usage_metadata=}')160161 print('\n\n', response.text)162163### JavaScript164165The following example shows how to generate content using a cached system166instruction and a text file.167168 import {169 GoogleGenAI,170 createUserContent,171 createPartFromUri,172 } from "@google/genai";173174 const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });175176 async function main() {177 const doc = await ai.files.upload({178 file: "path/to/file.txt",179 config: { mimeType: "text/plain" },180 });181 console.log("Uploaded file name:", doc.name);182183 const modelName = "gemini-3.8-flash";184 const cache = await ai.caches.create({185 model: modelName,186 config: {187 contents: createUserContent(createPartFromUri(doc.uri, doc.mimeType)),188 systemInstruction: "You are an expert analyzing transcripts.",189 },190 });191 console.log("Cache created:", cache);192193 const response = await ai.models.generateContent({194 model: modelName,195 contents: "Please summarize this transcript",196 config: { cachedContent: cache.name },197 });198 console.log("Response text:", response.text);199 }200201 await main();202203### Go204205The following example shows how to generate content using a cache.206207 package main208209 import (210 "context"211 "fmt"212 "log"213214 "google.golang.org/genai"215 )216217 func main() {218 ctx := context.Background()219 client, err := genai.NewClient(ctx, &genai.ClientConfig{220 APIKey: "GOOGLE_API_KEY",221 Backend: genai.BackendGeminiAPI,222 })223 if err != nil {224 log.Fatal(err)225 }226227 modelName := "gemini-3.8-flash"228 document, err := client.Files.UploadFromPath(229 ctx,230 "media/a11.txt",231 &genai.UploadFileConfig{232 MIMEType: "text/plain",233 },234 )235 if err != nil {236 log.Fatal(err)237 }238 parts := []*genai.Part{239 genai.NewPartFromURI(document.URI, document.MIMEType),240 }241 contents := []*genai.Content{242 genai.NewContentFromParts(parts, genai.RoleUser),243 }244 cache, err := client.Caches.Create(ctx, modelName, &genai.CreateCachedContentConfig{245 Contents: contents,246 SystemInstruction: genai.NewContentFromText(247 "You are an expert analyzing transcripts.", genai.RoleUser,248 ),249 })250 if err != nil {251 log.Fatal(err)252 }253 fmt.Println("Cache created:")254 fmt.Println(cache)255256 // Use the cache for generating content.257 response, err := client.Models.GenerateContent(258 ctx,259 modelName,260 genai.Text("Please summarize this transcript"),261 &genai.GenerateContentConfig{262 CachedContent: cache.Name,263 },264 )265 if err != nil {266 log.Fatal(err)267 }268 printResponse(response) // helper for printing response parts269 }270271### REST272273The following example shows how to create a cache and then use it to274generate content.275276### Videos277278 wget https://storage.googleapis.com/generativeai-downloads/data/a11.txt279 echo '{280 "model": "models/gemini-3.8-flash",281 "contents":[282 {283 "parts":[284 {285 "inline_data": {286 "mime_type":"text/plain",287 "data": "'$(base64 $B64FLAGS a11.txt)'"288 }289 }290 ],291 "role": "user"292 }293 ],294 "systemInstruction": {295 "parts": [296 {297 "text": "You are an expert at analyzing transcripts."298 }299 ]300 },301 "ttl": "300s"302 }' > request.json303304 curl -X POST "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GEMINI_API_KEY" \305 -H 'Content-Type: application/json' \306 -d @request.json \307 > cache.json308309 CACHE_NAME=$(cat cache.json | grep '"name":' | cut -d '"' -f 4 | head -n 1)310311 curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \312 -H 'Content-Type: application/json' \313 -d '{314 "contents": [315 {316 "parts":[{317 "text": "Please summarize this transcript"318 }],319 "role": "user"320 },321 ],322 "cachedContent": "'$CACHE_NAME'"323 }'324325### PDFs326327 DOC_URL="https://sma.nasa.gov/SignificantIncidents/assets/a11_missionreport.pdf"328 DISPLAY_NAME="A11_Mission_Report"329 SYSTEM_INSTRUCTION="You are an expert at analyzing transcripts."330 PROMPT="Please summarize this transcript"331 MODEL="models/gemini-3.8-flash"332 TTL="300s"333334 # Download the PDF335 wget -O "${DISPLAY_NAME}.pdf" "${DOC_URL}"336337 MIME_TYPE=$(file -b --mime-type "${DISPLAY_NAME}.pdf")338 NUM_BYTES=$(wc -c < "${DISPLAY_NAME}.pdf")339340 echo "MIME_TYPE: ${MIME_TYPE}"341 echo "NUM_BYTES: ${NUM_BYTES}"342343 tmp_header_file=upload-header.tmp344345 # Initial resumable request defining metadata.346 # The upload url is in the response headers dump them to a file.347 curl "${BASE_URL}/upload/v1beta/files?key=${GOOGLE_API_KEY}" \348 -D upload-header.tmp \349 -H "X-Goog-Upload-Protocol: resumable" \350 -H "X-Goog-Upload-Command: start" \351 -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \352 -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \353 -H "Content-Type: application/json" \354 -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null355356 upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")357 rm "${tmp_header_file}"358359 # Upload the actual bytes.360 curl "${upload_url}" \361 -H "Content-Length: ${NUM_BYTES}" \362 -H "X-Goog-Upload-Offset: 0" \363 -H "X-Goog-Upload-Command: upload, finalize" \364 --data-binary "@${DISPLAY_NAME}.pdf" 2> /dev/null > file_info.json365366 file_uri=$(jq ".file.uri" file_info.json)367 echo "file_uri: ${file_uri}"368369 # Clean up the downloaded PDF370 rm "${DISPLAY_NAME}.pdf"371372 # Create the cached content request373 echo '{374 "model": "'$MODEL'",375 "contents":[376 {377 "parts":[378 {"file_data": {"mime_type": "'$MIME_TYPE'", "file_uri": '$file_uri'}}379 ],380 "role": "user"381 }382 ],383 "system_instruction": {384 "parts": [385 {386 "text": "'$SYSTEM_INSTRUCTION'"387 }388 ],389 "role": "system"390 },391 "ttl": "'$TTL'"392 }' > request.json393394 # Send the cached content request395 curl -X POST "${BASE_URL}/v1beta/cachedContents?key=$GOOGLE_API_KEY" \396 -H 'Content-Type: application/json' \397 -d @request.json \398 > cache.json399400 CACHE_NAME=$(cat cache.json | grep '"name":' | cut -d '"' -f 4 | head -n 1)401 echo "CACHE_NAME: ${CACHE_NAME}"402 # Send the generateContent request using the cached content403 curl -X POST "${BASE_URL}/${MODEL}:generateContent?key=$GOOGLE_API_KEY" \404 -H 'Content-Type: application/json' \405 -d '{406 "contents": [407 {408 "parts":[{409 "text": "'$PROMPT'"410 }],411 "role": "user"412 }413 ],414 "cachedContent": "'$CACHE_NAME'"415 }' > response.json416417 cat response.json418419 echo jq ".candidates[].content.parts[].text" response.json420421### List caches422423It's not possible to retrieve or view cached content, but you can retrieve424cache metadata (`name`, `model`, `display_name`, `usage_metadata`,425`create_time`, `update_time`, and `expire_time`).426427### Python428429To list metadata for all uploaded caches, use `CachedContent.list()`:430431 for cache in client.caches.list():432 print(cache)433434To fetch the metadata for one cache object, if you know its name, use `get`:435436 client.caches.get(name=name)437438### JavaScript439440To list metadata for all uploaded caches, use `GoogleGenAI.caches.list()`:441442 console.log("My caches:");443 const pager = await ai.caches.list({ config: { pageSize: 10 } });444 let page = pager.page;445 while (true) {446 for (const c of page) {447 console.log(" ", c.name);448 }449 if (!pager.hasNextPage()) break;450 page = await pager.nextPage();451 }452453### Go454455The following example lists all caches.456457 caches, err := client.Caches.All(ctx)458 if err != nil {459 log.Fatal(err)460 }461 fmt.Println("Listing all caches:")462 for _, item := range caches {463 fmt.Println(" ", item.Name)464 }465466The following example lists caches using a page size of 2.467468 page, err := client.Caches.List(ctx, &genai.ListCachedContentsConfig{PageSize: 2})469 if err != nil {470 log.Fatal(err)471 }472473 pageIndex := 1474 for {475 fmt.Printf("Listing caches (page %d):\n", pageIndex)476 for _, item := range page.Items {477 fmt.Println(" ", item.Name)478 }479 if page.NextPageToken == "" {480 break481 }482 page, err = page.Next(ctx)483 if err == genai.ErrPageDone {484 break485 } else if err != nil {486 return err487 }488 pageIndex++489 }490491### REST492493 curl "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GEMINI_API_KEY"494495### Update a cache496497You can set a new `ttl` or `expire_time` for a cache. Changing anything else498about the cache isn't supported.499500### Python501502The following example shows how to update the `ttl` of a cache using503`client.caches.update()`.504505 from google import genai506 from google.genai import types507508 client.caches.update(509 name = cache.name,510 config = types.UpdateCachedContentConfig(511 ttl='300s'512 )513 )514515To set the expiry time, it will accepts either a `datetime` object516or an ISO-formatted datetime string (`dt.isoformat()`, like517`2025-01-27T16:02:36.473528+00:00`). Your time must include a time zone518(`datetime.utcnow()` doesn't attach a time zone,519`datetime.now(datetime.timezone.utc)` does attach a time zone).520521 from google import genai522 from google.genai import types523 import datetime524525 # You must use a time zone-aware time.526 in10min = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(minutes=10)527528 client.caches.update(529 name = cache.name,530 config = types.UpdateCachedContentConfig(531 expire_time=in10min532 )533 )534535### JavaScript536537The following example shows how to update the `ttl` of a cache using538`GoogleGenAI.caches.update()`.539540 const ttl = `${2 * 3600}s`; // 2 hours in seconds541 const updatedCache = await ai.caches.update({542 name: cache.name,543 config: { ttl },544 });545 console.log("After update (TTL):", updatedCache);546547### Go548549The following example shows how to update the `TTL` of a cache.550551 // Update the TTL (2 hours).552 cache, err = client.Caches.Update(ctx, cache.Name, &genai.UpdateCachedContentConfig{553 TTL: 7200 * time.Second,554 })555 if err != nil {556 log.Fatal(err)557 }558 fmt.Println("After update:")559 fmt.Println(cache)560561### REST562563The following example shows how to update the `ttl` of a cache.564565 curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY" \566 -H 'Content-Type: application/json' \567 -d '{"ttl": "600s"}'568569### Delete a cache570571The caching service provides a delete operation for manually removing content572from the cache. The following example shows how to delete a cache:573574### Python575576 client.caches.delete(cache.name)577578### JavaScript579580 await ai.caches.delete({ name: cache.name });581582### Go583584 _, err = client.Caches.Delete(ctx, cache.Name, &genai.DeleteCachedContentConfig{})585 if err != nil {586 log.Fatal(err)587 }588 fmt.Println("Cache deleted:", cache.Name)589590### REST591592 curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY"593594### Explicit caching using the OpenAI library595596If you're using an [OpenAI library](https://ai.google.dev/gemini-api/docs/openai), you can enable597explicit caching using the `cached_content` property on598[`extra_body`](https://ai.google.dev/gemini-api/docs/openai#extra-body).599600## When to use explicit caching601602Context caching is particularly well suited to scenarios where a substantial603initial context is referenced repeatedly by shorter requests. Consider using604context caching for use cases such as:605606- Chatbots with extensive [system instructions](https://ai.google.dev/gemini-api/docs/system-instructions)607- Repetitive analysis of lengthy video files608- Recurring queries against large document sets609- Frequent code repository analysis or bug fixing610611### How explicit caching reduces costs612613Context caching is a paid feature designed to reduce cost. Billing is based on614the following factors:6156161. **Cache token count:** The number of input tokens cached, billed at a reduced rate when included in subsequent prompts.6172. **Storage duration:** The amount of time cached tokens are stored (TTL), billed based on the TTL duration of cached token count. There are no minimum or maximum bounds on the TTL.6183. **Other factors:** Other charges apply, such as for non-cached input tokens and output tokens.619620For up-to-date pricing details, refer to the Gemini API [pricing621page](https://ai.google.dev/pricing). To learn how to count tokens, see the [Token622guide](https://ai.google.dev/gemini-api/docs/tokens).623624### Additional considerations625626Keep the following considerations in mind when using context caching:627628- The *minimum* input token count for context caching varies by model. The *maximum* is the same as the maximum for the given model. (For more on counting tokens, see the [Token guide](https://ai.google.dev/gemini-api/docs/tokens)).629- The model doesn't make any distinction between cached tokens and regular input tokens. Cached content is a prefix to the prompt.630- There are no special rate or usage limits on context caching; the standard rate limits for `GenerateContent` apply, and token limits include cached tokens.631- The number of cached tokens is returned in the `usage_metadata` from the create, get, and list operations of the cache service, and also in `GenerateContent` when using the cache.