Claude-promptcaching: 88% goedkoper bij 50.000 tokens

In een gepubliceerde ablatietest met Claude Sonnet 4.5 lagen de mediane API-kosten bij prompts van 50.000 tokens met caching 88% lager: $0,080 tegenover $0,667 zonder cache. De bedragen betreffen onderzochte agentsessies; de besparing is geen vaste korting op iedere aanvraag.

Zet voor hergebruik in de Claude API vaste instructies en context vooraan, markeer het laatste onveranderlijke blok met cache_control en plaats de actuele vraag daarna. De documentatie voor promptcaching beschrijft een standaardduur van vijf minuten, een duurdere optie van één uur en voor Claude Sonnet 4.5 een minimale cachebare prefix van 1.024 tokens.

Waar hoort de cachegrens?

Een cachehit vereist dezelfde promptprefix als bij de eerdere schrijfactie. De API leest de aanvraag in de volgorde tools, system en messages, tot en met het blok met cache_control. Een gewijzigde tooldefinitie raakt daardoor ook latere cacheblokken; een nieuwe gebruikersvraag na de grens laat de opgeslagen prefix intact.

De keuze voor een grens volgt uit wat tussen aanvragen gelijk blijft:

Zijn instructies, voorbeelden en achtergrondinformatie identiek? Markeer het laatste vaste tekstblok. Zet een tijdstempel, gebruikerswaarde of nieuwe zoekuitkomst erachter.
Blijven tooldefinities gelijk, terwijl systeemcontext vaker verandert? Markeer de laatste vaste tooldefinitie en eventueel ook het laatste stabiele systeemblok. Zo kan het eerdere deel bruikbaar blijven wanneer latere inhoud verandert.
Groeit een gesprek door nieuwe beurten toe te voegen? Automatische caching kan de grens laten meegroeien en eerdere inhoud teruglezen. Wordt het laatste blok bij iedere aanvraag vervangen, kies dan een expliciete grens vóór dat blok.

Een grens op een wisselende tijdstempel veroorzaakt bij iedere aanvraag een nieuwe prefix. De API kan dan een cache schrijven zonder de vorige ooit te lezen. Bij lange gesprekken speelt nog iets anders: vanaf een grens zoekt de API hoogstens twintig blokposities terug naar een eerder geschreven prefix. Een extra grens op een stabiele tussenstand kan voorkomen dat die schrijfactie buiten het zoekbereik valt.

Hoe stel je een vaste prefix in?

Gebruik in een Messages API-aanvraag een array system met een tekstblok. Dat blok bevat type: text, text met de herbruikbare inhoud en cache_control: {"type":"ephemeral"}. Plaats de actuele vraag afzonderlijk in messages. Voor een langere bewaartijd voeg je aan cache_control "ttl":"1h" toe.

De minimumlengte geldt voor de prefix tot aan de grens, niet voor de hele aanvraag. Is die prefix voor Claude Sonnet 4.5 korter dan de genoemde modeldrempel, dan verwerkt de API de aanvraag zonder cache en zonder foutmelding. Een kort voorbeeld met correct ingevulde velden laat dus alleen de syntaxis zien; het garandeert geen cachehit. De drempel verschilt bovendien per model.

De eerste aanvraag schrijft de gedeelde prefix zodra het antwoord begint. Een volgende aanvraag kan die prefix lezen als inhoud en bewaartermijn overeenkomen. Bij gelijktijdig gestarte aanvragen kan de eerste schrijfactie nog niet beschikbaar zijn voor de andere; laat die daarom pas starten nadat het eerste antwoord is begonnen als cachehits noodzakelijk zijn.

Wanneer kies je vijf minuten of één uur?

De standaardduur past bij een prefix die binnen vijf minuten opnieuw wordt gebruikt. Iedere hit ververst de bewaartermijn zonder een nieuwe schrijfactie. Die termijn loopt vanaf het begin van de aanvraag die schrijft of leest. Als het genereren van een lang antwoord veel tijd kost, blijft er na afloop minder tijd over voor de volgende aanvraag.

Kies één uur wanneer dezelfde context meestal later dan vijf minuten terugkomt, maar wel binnen een uur. Een hit wordt daardoor niet sneller dan een hit op de korte cache; de langere termijn voorkomt vooral dat de cache vóór de volgende aanvraag verloopt. Combineer je beide termijnen in één prompt, dan moet een grens van één uur vóór grenzen van vijf minuten staan.

Wat kosten schrijven en teruglezen?

De prijstabel van Claude vermeldt voor Sonnet 4.5 per miljoen inputtokens $3 voor gewone input, $3,75 voor een cachewrite van vijf minuten, $6 voor een cachewrite van één uur en $0,30 voor een cachehit. Schrijven kost dus eerst meer dan gewone input; de besparing ontstaat pas wanneer volgende aanvragen dezelfde prefix teruglezen.

Een voorwaardelijk voorbeeld met 50.000 identieke inputtokens maakt dat verschil zichtbaar. Twee aanvragen binnen vijf minuten kosten voor die gedeelde input $0,1875 voor de schrijfactie plus $0,015 voor de hit, samen $0,2025. Zonder cache zou dezelfde input bij twee aanvragen $0,30 kosten. Bij één uur kost de eerste schrijfactie $0,30 en één hit $0,015: samen $0,315. Pas met een tweede hit komt het totaal van drie aanvragen op $0,33 tegenover $0,45 zonder cache.

Dit rekenvoorbeeld betreft uitsluitend de gedeelde inputprefix. Wisselende input en outputtokens komen erbij; ook andere prijsaanpassingen kunnen het eindbedrag veranderen. De bedragen uit de agenttest hierboven omvatten daarentegen de gemeten kosten van volledige sessies met meerdere API-aanroepen. Je kunt die uitkomst daarom niet rechtstreeks als tarief op één herhaalde prompt toepassen.

Waarom kunnen toolresultaten de winst ondermijnen?

Een zoekresultaat of opgehaald record kan nodig zijn voor het antwoord, maar toch ongeschikt zijn voor hergebruik. Verandert het resultaat bij de volgende aanvraag, dan levert een expliciete cachegrens erachter een nieuwe schrijfactie op. Houd de grens daarom bij stabiele instructies en tooldefinities; geef veranderlijke resultaten daarna mee als gewone gespreksinhoud.

In de onderzochte agentopzet leverde het cachen van alleen de systeemprompt voor Claude Sonnet 4.5 iets meer kostenbesparing en een iets kortere tijd tot het eerste token op dan het cachen van de volledige context. Dat verschil was kleiner dan de totale winst door caching. De relevante keuze is welke inhoud opnieuw gelezen kan worden: een schrijfbeurt voor een eenmalig toolresultaat verdient zichzelf niet terug.

De API-respons maakt die keuze meetbaar. cache_creation_input_tokens telt geschreven tokens, cache_read_input_tokens telt gelezen tokens en input_tokens telt gewone input buiten de cache. Blijft het leesveld leeg bij een herhaalde aanvraag, vergelijk dan de prefix vóór de grens, de verstreken bewaartijd en de cachebare lengte. Stijgt vooral het schrijfveld na nieuwe toolresultaten, dan ligt de expliciete grens waarschijnlijk te ver naar achteren.