Context Caching & File API

Context caching — the 90% discount

If you're going to ask many questions against the same long context (a PDF, a codebase, a transcript), pay once to cache the context, then ask each question for ~10% of the per-token cost. Real numbers on Flash: $0.30/M for normal input → $0.03/M for cached input.

Minimum cacheable size

Flash: 1,024 tokens minimum.
Pro: 4,096 tokens minimum.

Below the minimum, caching is a no-op — you pay full input rate.

TTL is configurable

Default is 1 hour. Settable via ttl='300s' (or any duration string). The cache is billed per-token-hour, so a long TTL on a big context is its own cost. Match TTL to your actual reuse window.

File API for files that outlive a single call

Same File API as multimodal lessons. Files persist 48 hours, and you can attach them to multiple cache or generation calls during that window.

Code

Cache a PDF, ask many questions·python

from google import genai
from google.genai import types

client = genai.Client()

# 1. Upload the doc
doc = client.files.upload(
    file='whitepaper.pdf',
    config=dict(mime_type='application/pdf'),
)

# 2. Create a cache
cache = client.caches.create(
    model='gemini-2.5-flash',
    config=types.CreateCachedContentConfig(
        system_instruction='You are a precise document analyst.',
        contents=[doc],
        ttl='300s',  # 5 minutes; raise for longer reuse windows
    ),
)

# 3. Ask many questions, each cheap
for question in ['Summarize.', 'List the methods.', 'What's the headline result?']:
    response = client.models.generate_content(
        model='gemini-2.5-flash',
        contents=question,
        config=types.GenerateContentConfig(
            cached_content=cache.name,
        ),
    )
    print(question, '->', response.text[:120], '...')

# 4. Cleanup
client.caches.delete(name=cache.name)

File API — explicit upload + wait·python

import time

uploaded = client.files.upload(
    file='video.mp4',
    config=types.UploadFileConfig(display_name='intro_video'),
)

# Wait for processing if needed
while uploaded.state.name == 'PROCESSING':
    time.sleep(2.5)
    uploaded = client.files.get(name=uploaded.name)

# File is now usable for 48h
# Reuse across multiple calls — the upload is the expensive step
for question in ['Summarize the video.', 'What's the title slide say?']:
    response = client.models.generate_content(
        model='gemini-2.5-flash',
        contents=[uploaded, question],
    )
    print(response.text[:200])

client.files.delete(name=uploaded.name)

When NOT to cache·python

# Tiny context — cache overhead > benefit
context = 'Hello, world.'  # 4 tokens
# Don't cache. Just include in contents.

# One-shot question — never reused
context = open('huge_doc.txt').read()
questions = ['Summarize']  # only one
# Cache costs the same as one normal call. No win.

# Reuse > 4 — caching wins on Flash. Reuse > 6 — wins on Pro.
# Math: cache create cost ≈ 1.0× normal input.
# Per-question cached cost ≈ 0.1× normal input.
# Break-even at ~ 1 / (1 - 0.1) ≈ 1.1 reuses (after the first).

Exercise

Take a long document (a textbook chapter, a long README, a research paper PDF — anything ≥ 5K tokens). Run two experiments: (a) ask 5 questions without caching, time and price each call; (b) cache the doc, ask the same 5 questions, time and price each. Compare totals. Confirm caching is cheaper above the break-even and write the actual break-even point you measured.