Use Gemini Context Caching for Repeated Queries

Gemini context caching allows you to store the computed KV representations of a large document or system instruction and reference the cached content across multiple requests at a fraction of the full processing cost. For workflows where you run many queries against the same document — a legal contract, a codebase, a research paper — context caching reduces input token costs by up to 75%. This example shows how to create a cached context and reference it in subsequent requests. The caching workflow has three steps: first, create a cached content object using the cachedContents endpoint, specifying the content to cache and a time-to-live (TTL). Second, receive a cached content name in the response. Third, reference this name in subsequent generateContent requests using the cachedContent field. The cache is stored server-side; you only pay the lower cache read price for the cached tokens in all subsequent requests during the TTL. Context caching has a minimum token requirement (4,096 tokens) and a minimum duration (1 hour). The cost model is: you pay to create the cache (full input price), then a lower hourly storage fee while the cache is active, and a reduced per-request rate for cache reads. The break-even point is approximately 3-4 requests for a 1-hour cache, making it economical for any workflow with more than a few queries per document.

# Step 1: Create cached context
POST /v1beta/cachedContents
{
  "model": "models/gemini-1.5-pro",
  "systemInstruction": {"parts": [{"text": "You are a legal document analyst."}]},
  "contents": [{"role": "user", "parts": [{"text": "[Full 50,000-token contract text here]"}]}],
  "ttl": "3600s"
}

# Step 2: Use cached context (reference name from step 1)
POST /v1beta/models/gemini-1.5-pro:generateContent
{
  "cachedContent": "cachedContents/abc123",
  "contents": [{"role": "user", "parts": [{"text": "What are the termination clauses?"}]}]
}