◈ API / SDK/2026-03-24Advanced

Gemini API Context Caching— Cut Document Processing Costs by 90%

Learn how to use Gemini API's context caching to reduce repetitive document processing costs by up to 90%. Includes Python SDK implementation, caching strategies, and cost calculations.

Gemini API²⁰⁸ Context Caching⁵ Cost Optimization¹³ Python³⁸ Premium² Large-Scale Processing

✦ Premium Article

Setup and context: Why Context Caching Matters

When running Gemini API in production, the biggest cost driver is repeatedly sending large contexts. For instance, if you need to answer 100 questions about a 500-page technical manual, including the entire manual in every prompt leads to enormous token consumption.

Gemini API's Context Caching feature lets you cache large contexts once and reuse them across multiple requests, reducing input token costs by up to 90%.

What you'll learn:

How context caching works and its pricing model
Creating, using, and managing caches with the Python SDK
Cost optimization strategies for large document processing
Cache design patterns for production environments

How Context Caching Works

Basic Architecture

Context caching temporarily stores large contexts (documents, system prompts, code, etc.) on Google's servers. Subsequent requests reference a cache ID instead of re-sending the full context.

Standard request flow:

Request 1: [500-page manual] + Question 1 → Answer 1
Request 2: [500-page manual] + Question 2 → Answer 2
Request 3: [500-page manual] + Question 3 → Answer 3
→ Manual tokens are billed every single time

With caching:

Cache creation: [500-page manual] → Cache ID
Request 1: [Cache ID] + Question 1 → Answer 1 (cached tokens at discount)
Request 2: [Cache ID] + Question 2 → Answer 2 (cached tokens at discount)
Request 3: [Cache ID] + Question 3 → Answer 3 (cached tokens at discount)

Pricing

Context cache input tokens are priced at approximately 75% less than standard input tokens (as of March 2026).

Item	Standard Input	Cached Input	Savings
Gemini 2.5 Pro	$1.25/MTok	$0.3125/MTok	75%
Gemini 2.5 Flash	$0.075/MTok	$0.01875/MTok	75%

Note: MTok = 1 million tokens. Cache storage costs ($4.50/MTok/hour for Pro) apply separately.

✦

Thank you for reading this far.

Continue Reading

What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.

WHAT YOU'LL LEARN

✦Cost optimization for Gemini API calls using Context Caching

✦Cost reduction patterns for large-scale text processing

✦Best practices for caching strategies

Secure payment via Stripe · Cancel anytime

✦

Unlock This Article

Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.

Unlock all articles with Membership →

Creating Caches with the Python SDK

Basic Cache Creation

# cache_setup.py — Creating a context cache
import google.generativeai as genai
from datetime import timedelta
 
# Configure API key
genai.configure(api_key="YOUR_API_KEY")
 
# Load the document to cache
with open("technical_manual.pdf", "rb") as f:
    pdf_data = f.read()
 
# Create the cache
cache = genai.caching.CachedContent.create(
    model="models/gemini-2.5-pro",
    display_name="Technical Manual v3.2",
    system_instruction=(
        "You are a technical manual assistant. "
        "Answer questions accurately based on the manual content. "
        "If information is not in the manual, explicitly state so."
    ),
    contents=[
        genai.protos.Content(
            parts=[
                genai.protos.Part(
                    inline_data=genai.protos.Blob(
                        mime_type="application/pdf",
                        data=pdf_data,
                    )
                )
            ],
            role="user",
        )
    ],
    ttl=timedelta(hours=2),  # 2-hour TTL
)
 
print(f"Cache created: {cache.name}")
print(f"Token count: {cache.usage_metadata.total_token_count:,}")
print(f"Expires: {cache.expire_time}")
 
# Expected output:
# Cache created: cachedContents/abc123xyz
# Token count: 328,450
# Expires: 2026-03-24T18:00:00Z

Querying with a Cache

# cache_query.py — Running queries against a cached context
import google.generativeai as genai
 
genai.configure(api_key="YOUR_API_KEY")
 
# Create a model from the cache
model = genai.GenerativeModel.from_cached_content(cached_content=cache)
 
# Process multiple questions efficiently
questions = [
    "What's the resolution for error code E-201 in Chapter 3?",
    "List all new features added in version 3.2",
    "Summarize the troubleshooting flowchart",
    "What authentication method does the API endpoint use?",
    "What are the recommended performance tuning settings?",
]
 
for i, question in enumerate(questions, 1):
    response = model.generate_content(question)
    print(f"\n--- Question {i}: {question}")
    print(f"Answer: {response.text[:200]}...")
    print(f"Input tokens: {response.usage_metadata.prompt_token_count:,}")
    print(f"  Cached: {response.usage_metadata.cached_content_token_count:,}")
 
# Expected output:
# --- Question 1: What's the resolution for error code E-201 in Chapter 3?
# Answer: E-201 is a connection timeout error. Follow these steps to resolve it...
# Input tokens: 328,480
#   Cached: 328,450 (← cached tokens billed at discount rate)

Concrete Cost Calculations

Scenario: Technical Manual Q&A Bot

Let's compare costs with and without caching under these conditions:

Document: 328,450 tokens (~500-page PDF)
Questions: 100/day
Average question: 50 tokens
Average answer: 300 tokens
Model: Gemini 2.5 Pro

# cost_calculator.py — Cost comparison
def calculate_costs(
    doc_tokens: int = 328_450,
    questions_per_day: int = 100,
    avg_question_tokens: int = 50,
    avg_answer_tokens: int = 300,
    cache_hours: int = 8,
):
    # Gemini 2.5 Pro pricing (March 2026)
    INPUT_PRICE = 1.25 / 1_000_000   # $/token
    CACHED_PRICE = 0.3125 / 1_000_000  # $/token
    OUTPUT_PRICE = 5.00 / 1_000_000   # $/token
    CACHE_STORAGE = 4.50 / 1_000_000  # $/token/hour
 
    # --- Without cache ---
    daily_input_no_cache = questions_per_day * (doc_tokens + avg_question_tokens)
    daily_output = questions_per_day * avg_answer_tokens
 
    cost_no_cache = (daily_input_no_cache * INPUT_PRICE) + (daily_output * OUTPUT_PRICE)
 
    # --- With cache ---
    cache_creation = doc_tokens * INPUT_PRICE  # One-time cost
    cache_storage = doc_tokens * CACHE_STORAGE * cache_hours
    daily_cached_input = questions_per_day * doc_tokens * CACHED_PRICE
    daily_new_input = questions_per_day * avg_question_tokens * INPUT_PRICE
 
    cost_with_cache = cache_creation + cache_storage + daily_cached_input + daily_new_input + (daily_output * OUTPUT_PRICE)
 
    savings = (1 - cost_with_cache / cost_no_cache) * 100
 
    print(f"=== Daily Cost Comparison ===")
    print(f"Without cache: ${cost_no_cache:.2f}")
    print(f"With cache: ${cost_with_cache:.2f}")
    print(f"Savings: ${cost_no_cache - cost_with_cache:.2f}")
    print(f"Reduction: {savings:.1f}%")
 
calculate_costs()
 
# Expected output:
# === Daily Cost Comparison ===
# Without cache: $41.21
# With cache: $12.24
# Savings: $28.97
# Reduction: 70.3%

The more questions you process, the greater the savings. At 500 questions per day, the reduction reaches approximately 85%.

Cache Management Best Practices

Optimal TTL Settings

# cache_management.py — Cache lifecycle management
import google.generativeai as genai
from datetime import timedelta
 
genai.configure(api_key="YOUR_API_KEY")
 
# List existing caches
caches = list(genai.caching.CachedContent.list())
for c in caches:
    print(f"  {c.display_name}: {c.usage_metadata.total_token_count:,} tokens, expires {c.expire_time}")
 
# Extend TTL
cache = genai.caching.CachedContent.get("cachedContents/abc123xyz")
cache.update(ttl=timedelta(hours=4))
print(f"TTL updated: {cache.expire_time}")
 
# Delete cache
cache.delete()
print("Cache deleted")
 
# Expected output:
#   Technical Manual v3.2: 328,450 tokens, expires 2026-03-24T18:00:00Z
# TTL updated: 2026-03-24T20:00:00Z
# Cache deleted

Recommended TTL by Use Case

Use Case	Recommended TTL	Reason
Customer support bot	12–24 hours	Active during business hours
Batch document processing	1–2 hours	Not needed after processing
Daily report generation	2–4 hours	Only during report generation
Code review assistant	4–8 hours	During the review session

Multi-Document Caching Strategy

# multi_doc_cache.py — Caching multiple documents together
import google.generativeai as genai
from pathlib import Path
from datetime import timedelta
 
genai.configure(api_key="YOUR_API_KEY")
 
def create_multi_doc_cache(doc_paths: list[str], display_name: str, ttl_hours: int = 4):
    """Bundle multiple documents into a single cache"""
    parts = []
    for path in doc_paths:
        file_path = Path(path)
        mime_type = {
            ".pdf": "application/pdf",
            ".txt": "text/plain",
            ".md": "text/markdown",
            ".py": "text/x-python",
        }.get(file_path.suffix, "text/plain")
 
        with open(path, "rb") as f:
            parts.append(
                genai.protos.Part(
                    inline_data=genai.protos.Blob(
                        mime_type=mime_type,
                        data=f.read(),
                    )
                )
            )
 
    cache = genai.caching.CachedContent.create(
        model="models/gemini-2.5-pro",
        display_name=display_name,
        contents=[
            genai.protos.Content(parts=parts, role="user")
        ],
        ttl=timedelta(hours=ttl_hours),
    )
 
    print(f"Cache created: {cache.name}")
    print(f"Total tokens: {cache.usage_metadata.total_token_count:,}")
    return cache
 
# Usage
cache = create_multi_doc_cache(
    doc_paths=[
        "docs/api_reference.pdf",
        "docs/architecture.md",
        "docs/changelog.txt",
    ],
    display_name="Project Documentation Bundle",
    ttl_hours=8,
)
 
# Expected output:
# Cache created: cachedContents/def456uvw
# Total tokens: 512,300

Where Caching Actually Pays Off

Context caching is not a feature that always lowers your bill. When I was testing a setup in my own indie projects, the first few days were actually cheaper without a cache. Requests were sparse, and the storage fee quietly piled up on its own.

Whether caching pays off comes down to a rough break-even point: divide the fixed cost (cache creation plus storage) by the savings per request.

# break_even.py — estimate the break-even point for caching
def break_even_requests(doc_tokens: int, cache_hours: int) -> float:
    INPUT = 1.25 / 1_000_000
    CACHED = 0.3125 / 1_000_000
    STORAGE = 4.50 / 1_000_000
    # Fixed cost: creation (one full input) + storage (for the TTL window)
    fixed = doc_tokens * INPUT + doc_tokens * STORAGE * cache_hours
    # Savings per request: full-input price -> cached price
    saved_per_req = doc_tokens * (INPUT - CACHED)
    return fixed / saved_per_req
 
for h in (8, 4, 1):
    n = break_even_requests(328_450, cache_hours=h)
    print(f"TTL {h}h: ~{n:.0f} requests to break even")
 
# Expected output:
# TTL 8h: ~40 requests to break even
# TTL 4h: ~23 requests to break even
# TTL 1h: ~6 requests to break even

Because storage dominates the fixed cost, the shorter you keep the TTL, the lower the break-even point. Just remember that for validation work or sparse traffic, a longer TTL makes caching less favorable — keeping that in mind will stop you from misjudging when to cache.

My first attempts at creating a cache tripped on three things, none of which are obvious from the pricing table alone:

Minimum token threshold: Explicit caches have a per-model minimum token count, and passing a short document gets the creation rejected. Caching is effective for documents spanning hundreds of pages, but don't force a few-thousand-token passage into a cache.
Pinning the model ID: The model used at cache creation must match the model used at inference, or the cache won't be referenced. If you use an auto-upgrading alias, the cache silently becomes invalid the moment the model rolls over underneath you. Pin a versioned ID like models/gemini-2.5-pro to stay safe.
TTL expiry is silent: An expired cache lapses without raising an exception, and the next call falls back to full-context billing. Add a check that detects expiry and logs it, so you aren't caught off guard after the bill grows.

A Note from an Indie Developer

When I first started running a document Q&A setup in my own indie projects, I assumed a cache was simply "safe to leave on." A week of real usage broke that assumption: traffic was intermittent during testing, and the storage fee was the only thing doing any work.

So I split the operation in two. Keep the TTL short during the validation phase, and switch to a longer TTL only during the hours when traffic concentrates in production. That one change alone brought the monthly bill back to a visible, predictable level.

The other lesson was how much it helps to log cache-hit status every time. Recording cached_content_token_count from usage_metadata makes it immediately clear whether the cache is hitting as expected, or quietly being skipped because of a model-ID mismatch. Cost optimization, I've come to feel, is less about flashy moves and more about this kind of unglamorous, steady measurement.

Wrapping Up: Dramatically Reduce API Costs with Context Caching

This guide covered how to optimize costs using Gemini API's context caching:

How it works: Store large contexts server-side and reuse across multiple requests
Python SDK implementation: Complete code examples for creating, using, and managing caches
Cost savings: ~70% reduction at 100 questions/day, ~85% at 500 questions/day
Production best practices: TTL design, multi-document management, lifecycle management

For any workflow involving repeated processing of large documents, context caching is an essential optimization technique. For broader Gemini API cost management, see "[Gemini API Long Context Strategies Guide]((/articles/gemini-api/gemini-long-context-strategies)". For API fundamentals, check out "[Gemini API Advanced Tool Use Guide]((/articles/gemini-api/gemini-api-tool-use-advanced)".

Thank You for Reading

Gemini Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.