#gemini api

Gemini API Context Caching Planner: Implicit vs Explicit Caching on Gemini 2.5 Models, google-genai caches.create with TTL, Minimum Cacheable Tokens, Stable Prefix Prompt Layout, Storage vs Input Cost Math, and Cache Hit Monitoring

Decide whether and how to cache a large repeated context in the Gemini API: compare implicit caching with explicit caches, lay out prompts so the stable part comes first, create and refresh a cache with the google-genai SDK and a TTL that matches your traffic, check the cost against storage charges using the rates you paste, and confirm hits in usage metadata.

Act as a backend engineer who runs production apps on the Gemini API, has cut monthly token bills by caching large shared contexts, and has debugged the error you get when a request sends a system instruction alongside a cached context. Inputs: - The workload: requests per day, hours when traffic arrives, shared context size in tokens, and typical question size: [Workload] - What repeats across requests (system instruction, manuals, codebase, a long video or PDF) and how often it changes: [SharedContext] - Model and SDK in use: [ModelChoice] - Rates copied from the current Gemini pricing page for input, cached input, and cache storage: [PricingNotes] - Current prompt structure or code snippet: [CurrentCode] - Output format: [Format] Generate: 1. An implicit versus explicit decision: implicit caching is on by default for Gemini 2.5 models and gives a discount only when a request shares a prefix with a recent one, with no guarantee; explicit caching stores the context for a TTL you pay storage for, and gives a predictable discount. Pick one for this Workload and say why. 2. Prompt layout rules for either mode: put the large stable content first and the per request question last, keep the stable part byte identical, and send similar requests close together in time. 3. A minimum size check: explicit caches need a minimum number of input tokens that differs by model; tell the user to measure with client.models.count_tokens and compare against the current minimum for ModelChoice from the docs. 4. Python code with the google-genai SDK: client.caches.create with model, a CreateCachedContentConfig holding display_name, system_instruction, contents, and ttl; then client.models.generate_content with GenerateContentConfig(cached_content=cache.name). Put system_instruction and tools in the cache, not in the request, because the request cannot set them when it uses cached content. 5. TTL and refresh: choose a TTL from the traffic hours in Workload, extend it with client.caches.update when traffic continues, and delete it with client.caches.delete when the day ends. 6. Versioning: caches are not edited in place; create a new cache when SharedContext changes, and put the content version in display_name. 7. Cost math using only PricingNotes: daily cost without caching, with explicit caching (cached tokens at the cached rate plus storage tokens times hours), and the break even request count. 8. Monitoring: log usage_metadata.cached_content_token_count and prompt_token_count per request, alert when the cached share drops, and recreate the cache on a not found error after expiry. Constraints: - Never invent prices or token minimums; use PricingNotes and mark anything else "confirm in the current Gemini docs". - The cache model must match the request model exactly. No em dashes.