Context Caching

Context caching stores processed tokens for reuse, reducing costs when repeatedly querying the same large context.

Creating a Cache

const cache = await ai.caches.create({
  model: "gemini-2.5-flash",
  config: {
    contents: [{
      role: "user",
      parts: [{ text: entireCodebase }] // Large context
    }],
    systemInstruction: "You are an expert code reviewer.",
    ttl: "3600s", // 1 hour
  },
});

Using a Cached Context

const response = await ai.models.generateContent({
  model: "gemini-2.5-flash",
  cachedContent: cache.name,
  contents: "Find potential security vulnerabilities",
});

When to Use Caching

• Processing the same large document with multiple queries
• Chatbots with extensive system instructions or knowledge bases
• Code review across multiple files with shared context
• Document Q&A where users ask many questions about the same content

Cache Management

• Minimum size: 32,768 tokens
• TTL options: Set explicit TTL or let it expire automatically
• Update: Modify TTL on existing caches
• Delete: Remove caches when no longer needed
• Cost: Cache storage is charged per token-hour

Common Pitfall: Setting TTL Too Long for Infrequently Used Caches

Cache storage is billed per token-hour. A 100K-token cache with a 24-hour TTL that is only queried 3 times costs far more in storage than those 3 queries save. Calculate the break-even point before setting TTLs:

Break-even queries = (cache_storage_cost_per_hour * ttl_hours) / (input_token_price * cached_tokens)

For most workloads, a 1-hour TTL with periodic refresh is more cost-effective than a 24-hour TTL.

Best Practice: Warm the Cache Before Peak Traffic

Cache hits require the cache to already exist. Pre-create caches before expected high-traffic periods (e.g., batch create all document caches at midnight for a Q&A service that spikes during business hours):

// Pre-warm cache at startup
const docCache = await ai.caches.create({
  model: "gemini-2.5-flash",
  config: {
    contents: [{ role: "user", parts: [{ text: knowledgeBase }] }],
    ttl: "7200s",  // 2 hours
  },
});

// Store cache name for use in subsequent requests
await redis.set("doc_cache_name", docCache.name, "EX", 7000);

Named Product Reference: Google Gemini for Workspace

Google has integrated Gemini into Workspace (Docs, Sheets, Gmail). For enterprise applications that need to process documents stored in Google Drive, the Workspace Gemini APIs can access and analyze Drive files directly without downloading them — eliminating the need to manage file uploads and caches manually in many document Q&A use cases.