Context caching voor goedkopere Gemini API-calls

Wat is context caching

Bij elke Gemini API-call worden alle tokens in de prompt opnieuw verwerkt en gefactureerd. Als je steeds dezelfde grote context meestuurt (een handboek van 200 pagina's, een uitgebreide system instruction, een grote dataset), betaal je telkens opnieuw voor die tokens.

Context caching lost dit op: je slaat de grote context eenmalig op bij Google, ontvangt een cache-naam en verwijst daarna naar die naam in je API-calls. Je betaalt dan alleen de volle prijs voor de kleinere vraag die je bovenop de gecachte context plaatst, plus een sterk verlaagd tarief voor de gecachte tokens zelf.

Er zijn twee varianten:

• Impliciete caching staat sinds Gemini 2.5 standaard aan. Google detecteert automatisch herhaalde prefixen en geeft de korting door zonder dat je iets hoeft te doen. Je hebt er geen garantie op, want of een call de cache raakt hangt af van timing en verkeer.
• Expliciete caching maak je zelf aan via de caches-API. Je krijgt volledige controle en een gegarandeerde korting op de tokens die naar de cache verwijzen. Dit artikel richt zich op expliciete caching, omdat dat het meeste oplevert bij hoge volumes.

De korting op gecachte input-tokens is op Gemini 2.5 en nieuwere modellen 90 procent ten opzichte van de normale input-prijs.

Cache aanmaken

from google import genai
from google.genai import types

client = genai.Client()

document = client.files.upload(file="handleiding.pdf")

cache = client.caches.create(
    model="models/gemini-2.5-flash",
    config=types.CreateCachedContentConfig(
        display_name="Producthandleiding Q2 2026",
        system_instruction=(
            "Je bent een productspecialist. "
            "Beantwoord vragen over de handleiding nauwkeurig."
        ),
        contents=[document],
        ttl="86400s",
    ),
)

print(f"Cache aangemaakt: {cache.name}")
print(f"Tokens gecachet: {cache.usage_metadata.total_token_count}")
print(f"Verloopt op: {cache.expire_time}")

De ttl (time to live) geef je op als een string in seconden, bijvoorbeeld "86400s" voor 24 uur. Standaard staat de ttl op 1 uur als je niets opgeeft.

Cache gebruiken in API-calls

Verwijs naar de cache via cached_content in de GenerateContentConfig. Geef hetzelfde model op als waarmee je de cache hebt aangemaakt.

vragen = [
    "Wat zijn de technische specificaties van product X?",
    "Hoe installeer ik product X stap voor stap?",
    "Wat zijn bekende problemen en oplossingen?",
]

for vraag in vragen:
    response = client.models.generate_content(
        model="models/gemini-2.5-flash",
        contents=vraag,
        config=types.GenerateContentConfig(cached_content=cache.name),
    )
    print(f"V: {vraag}")
    print(f"A: {response.text}")
    print(
        "Tokens: prompt="
        f"{response.usage_metadata.prompt_token_count}, "
        "cache_hit="
        f"{response.usage_metadata.cached_content_token_count}"
    )

Cache-levensduur beheren

Je kunt de ttl van een bestaande cache verlengen zonder de inhoud opnieuw te uploaden.

client.caches.update(
    name=cache.name,
    config=types.UpdateCachedContentConfig(ttl="172800s"),
)

Bestaande caches oplijsten

for item in client.caches.list():
    print(f"Naam: {item.name}")
    print(f"Display: {item.display_name}")
    print(f"Tokens: {item.usage_metadata.total_token_count}")
    print(f"Verloopt: {item.expire_time}")
    print("---")

Cache verwijderen

Een cache vervalt automatisch na de ttl, maar je kunt hem ook handmatig opruimen om opslagkosten te beperken.

client.caches.delete(name=cache.name)
print("Cache verwijderd")

Kostenberekening

De onderstaande tarieven gelden voor Gemini 2.5 Flash (juni 2026). Controleer altijd de officiële prijspagina, want tarieven veranderen.

Voorbeeld: een handleiding van 100.000 tokens, 1000 vragen per dag, cache 24 uur in leven.

• Zonder cache: 100.000 tokens maal 1000 calls is 100M tokens input per dag, maal 0,30 dollar is 30,00 dollar per dag.
• Met cache:
  • Opslag: 0,1M tokens maal 1,00 dollar per uur maal 24 uur is 2,40 dollar.
  • Gecachte input lezen: 100M tokens maal 0,03 dollar is 3,00 dollar.
  • Verse vraagtekst: 1000 maal ongeveer 500 tokens is 0,5M tokens maal 0,30 dollar is 0,15 dollar.
  • Totaal ongeveer 5,55 dollar per dag tegenover 30,00 dollar zonder cache. Dat is een besparing van circa 81 procent.

De winst groeit naarmate je meer queries op dezelfde context draait en de context groter is. Bij weinig herhaling kan de opslagkost juist duurder uitvallen dan steeds opnieuw versturen.

Cache combineren met de Files API

Voor grote bestanden upload je eerst via de Files API en verwijs je naar het resultaat in de cache. Zo hoef je de inhoud niet inline te base64-coderen.

from google import genai
from google.genai import types

client = genai.Client()

rapport = client.files.upload(file="groot_rapport.pdf")

cache = client.caches.create(
    model="models/gemini-2.5-flash",
    config=types.CreateCachedContentConfig(
        contents=[rapport],
        ttl="43200s",
    ),
)

response = client.models.generate_content(
    model="models/gemini-2.5-flash",
    contents="Wat zijn de aanbevelingen in sectie 4?",
    config=types.GenerateContentConfig(cached_content=cache.name),
)
print(response.text)