Reuse large Gemini context when repeated requests justify the cache.
Context caching lets applications reuse large, repeated input such as documents, media, code, or extensive system instructions. It can reduce repeated processing cost and latency, but only when cache reuse, lifetime, model support, and storage risk fit the workload.
Caching decisions at a glance
Implicit caching
Some supported models may automatically reuse matching prompt prefixes. Applications do not create or manage a cache resource.
Explicit caching
Create a reusable cached-content resource, reference it in later requests, and manage its lifetime directly.
Reuse economics
Caching is most useful when a large stable prefix is reused enough times before it expires to offset storage and setup cost.
Data lifecycle
Cached content has retention and access implications. Apply least privilege, expiration, deletion, regional, and privacy controls.
Choose a suitable workload
Good candidates have a large stable context followed by many smaller questions: a long manual, video, codebase, policy collection, or extensive system instruction. One-off prompts and frequently changing context usually gain less.
- Estimate context size, expected cache hits, lifetime, and request frequency.
- Keep the reusable prefix stable and place changing user input after it.
- Compare total uncached cost with cache creation, storage, and cached-input charges.
Understand implicit and explicit caching
Implicit caching is automatic on supported models and may report cached tokens in usage metadata. Explicit caching creates a named resource that later generation requests reference, giving the application more predictable reuse and lifecycle control.
- Do not assume every model, input type, or request is eligible for caching.
- Inspect cached-content token metadata rather than inferring a hit from latency alone.
- Use explicit caching when controlled reuse and a managed TTL matter to the design.
Create and reference cached content
With explicit caching, create the cache using a supported model and repeated content, then pass the returned cached-content name in later generation configuration. Keep dynamic questions outside the cached resource.
- Use a descriptive display name and store the provider resource name with your application record.
- Set a TTL aligned with the real reuse window and refresh it only when necessary.
- Handle cache creation, lookup, expiration, deletion, and fallback to an uncached request.
Measure cost and latency
A cache is an optimization that should be proven with production-like measurements. Track creation latency, hit rate, cached and uncached input tokens, storage duration, end-to-end latency, and total cost per completed task.
- Benchmark against an uncached baseline using the same model and content.
- Separate time to first token from total response time for streaming interfaces.
- Revisit the decision when pricing, token thresholds, model support, or traffic patterns change.
Protect cached data
Cached content can include documents, media, source code, and system instructions. Treat the cache as stored data: minimize content, control access, define deletion, and review provider retention and regional behavior.
- Do not cache secrets or data that the application is not authorized to retain.
- Keep cache identifiers server-side and authorize every request that references them.
- Delete obsolete caches and document incident, privacy, and retention procedures.
Python
This simplified flow creates cached content with a one-hour TTL and references it in a later request. Replace the placeholder with eligible repeated context and verify current SDK syntax.
import os
from google import genai
from google.genai import types
client = genai.Client()
model = os.environ["GEMINI_MODEL"]
cached = client.caches.create(
model=model,
config=types.CreateCachedContentConfig(
display_name="product-manual",
contents=["<large repeated context>"],
ttl="3600s",
),
)
response = client.models.generate_content(
model=model,
contents="Summarize the upgrade procedure.",
config=types.GenerateContentConfig(cached_content=cached.name),
)
print(response.text)