What is context caching in the Gemini API and how does it reduce costs?

from google import genai
from google.genai import types
from datetime import timedelta

client = genai.Client()

# Create a cache with large stable content:
large_document = open("entire-codebase.py").read()  # 500k tokens

cached = client.caches.create(
    model="gemini-3.5-flash",
    config=types.CreateCachedContentConfig(
        contents=[
            types.Content(
                parts=[types.Part(text=large_document)]
            )
        ],
        system_instruction="You are a code review expert. Always give actionable feedback.",
        ttl=timedelta(hours=2),  # cache lives for 2 hours
        display_name="codebase-cache",
    )
)
print(f"Cache name: {cached.name}")
print(f"Cached tokens: {cached.usage_metadata.total_token_count}")

# Use the cache across many requests:
for pr_diff in pull_requests:
    response = client.models.generate_content(
        model="gemini-3.5-flash",
        contents=pr_diff,  # only the diff changes per request
        config=types.GenerateContentConfig(
            cached_content=cached.name
        )
    )
    # You pay full price for pr_diff tokens
    # but discounted price for the 500k cached codebase tokens
    print(response.text)

# Delete cache when done:
client.caches.delete(name=cached.name)