Prompt-Caching

Prompt-Caching optimiert deine API-Nutzung, indem es das Fortsetzen ab bestimmten Präfixen in deinen Prompts ermöglicht. Dies reduziert die Verarbeitungszeit und Kosten für sich wiederholende Aufgaben oder Prompts mit gleichbleibenden Elementen erheblich.

Es gibt zwei Möglichkeiten, Prompt-Caching zu aktivieren:

• Automatisches Caching: Füge ein einzelnes cache_control-Feld auf der obersten Ebene deiner Anfrage hinzu. Das System wendet den Cache-Breakpoint automatisch auf den letzten cachefähigen Block an und verschiebt ihn nach vorne, wenn Konversationen wachsen. Am besten geeignet für mehrstufige Konversationen, bei denen der wachsende Nachrichtenverlauf automatisch gecacht werden soll.
• Explizite Cache-Breakpoints: Platziere cache_control direkt auf einzelnen Content-Blöcken für eine feingranulare Kontrolle darüber, was genau gecacht wird.

Der einfachste Einstieg ist das automatische Caching:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
    messages=[
        {
            "role": "user",
            "content": "Analyze the major themes in 'Pride and Prejudice'.",
        }
    ],
)
print(response.usage.model_dump_json())

Beim automatischen Caching cacht das System alle Inhalte bis einschließlich des letzten cachefähigen Blocks. Bei nachfolgenden Anfragen mit demselben Präfix wird der gecachte Inhalt automatisch wiederverwendet.



So funktioniert Prompt-Caching

Wenn du eine Anfrage mit aktiviertem Prompt-Caching sendest:

1. Das System prüft, ob ein Prompt-Präfix bis zu einem angegebenen Cache-Breakpoint bereits aus einer kürzlichen Abfrage gecacht ist.
2. Falls gefunden, verwendet es die gecachte Version, was Verarbeitungszeit und Kosten reduziert.
3. Andernfalls verarbeitet es den vollständigen Prompt und cacht das Präfix, sobald die Antwort beginnt.

Dies ist besonders nützlich für:

• Prompts mit vielen Beispielen
• Große Mengen an Kontext oder Hintergrundinformationen
• Sich wiederholende Aufgaben mit gleichbleibenden Anweisungen
• Lange mehrstufige Konversationen

Standardmäßig hat der Cache eine Lebensdauer von 5 Minuten. Der Cache wird ohne zusätzliche Kosten jedes Mal aktualisiert, wenn der gecachte Inhalt verwendet wird.

Die Lebensdauer wird ab dem Start der Anfrage gemessen, die den Cache-Eintrag schreibt oder liest, nicht ab dem Ende ihrer Antwort. Die für die Generierung einer Antwort aufgewendete Zeit zählt gegen die Lebensdauer: Wenn das Streaming einer Antwort 4 Minuten dauert, muss eine Folgeanfrage, die dasselbe gecachte Präfix wiederverwendet, innerhalb von etwa 1 Minute nach Abschluss dieser Antwort starten.



Preise

Prompt-Caching führt eine neue Preisstruktur ein. Die folgende Tabelle zeigt den Preis pro Million Token für jedes unterstützte Modell:



Unterstützte Modelle

Prompt-Caching (sowohl automatisch als auch explizit) wird auf allen aktiven Claude-Modellen unterstützt.



Automatisches Caching

Automatisches Caching ist der einfachste Weg, Prompt-Caching zu aktivieren. Anstatt cache_control auf einzelnen Content-Blöcken zu platzieren, fügst du ein einzelnes cache_control-Feld auf der obersten Ebene deines Request-Bodys hinzu. Das System wendet den Cache-Breakpoint automatisch auf den letzten cachefähigen Block an.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are a helpful assistant that remembers our conversation.",
    messages=[
        {"role": "user", "content": "My name is Alex. I work on machine learning."},
        {
            "role": "assistant",
            "content": "Nice to meet you, Alex! How can I help with your ML work today?",
        },
        {"role": "user", "content": "What did I say I work on?"},
    ],
)
print(response.usage.model_dump_json())



So funktioniert automatisches Caching in mehrstufigen Konversationen

Beim automatischen Caching bewegt sich der Cache-Punkt automatisch nach vorne, wenn Konversationen wachsen. Jede neue Anfrage cacht alles bis zum letzten cachefähigen Block, und vorheriger Inhalt wird aus dem Cache gelesen.

Der Cache-Breakpoint bewegt sich automatisch zum letzten cachefähigen Block in jeder Anfrage, sodass du keine cache_control-Markierungen aktualisieren musst, wenn die Konversation wächst.



TTL-Unterstützung

Standardmäßig verwendet automatisches Caching eine 5-Minuten-TTL. Du kannst eine 1-Stunden-TTL zum 2-fachen Basispreis für Input-Token angeben:

{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }



Kombination mit Block-Level-Caching

Automatisches Caching ist mit expliziten Cache-Breakpoints kompatibel. Wenn beide zusammen verwendet werden, belegt der automatische Cache-Breakpoint einen der 4 verfügbaren Breakpoint-Slots.

So kannst du beide Ansätze kombinieren. Verwende zum Beispiel einen expliziten Breakpoint, um deinen System-Prompt zu cachen, während das automatische Caching die Konversation übernimmt:

{
  "model": "claude-opus-5",
  "max_tokens": 1024,
  "cache_control": { "type": "ephemeral" },
  "system": [
    {
      "type": "text",
      "text": "You are a helpful assistant.",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "What are the key terms?" }]
}



Was gleich bleibt

Automatisches Caching verwendet dieselbe zugrunde liegende Caching-Infrastruktur. Preise, Mindest-Token-Schwellenwerte, Anforderungen an die Kontextreihenfolge und das 20-Block-Lookback-Fenster gelten alle genauso wie bei expliziten Breakpoints.



Sonderfälle

• Wenn der letzte Block bereits ein explizites cache_control mit derselben TTL hat, ist das automatische Caching eine No-Op.
• Wenn der letzte Block ein explizites cache_control mit einer anderen TTL hat, gibt die API einen 400-Fehler zurück.
• Wenn bereits 4 explizite Block-Level-Breakpoints existieren, gibt die API einen 400-Fehler zurück (keine Slots mehr für automatisches Caching übrig).
• Wenn der letzte Block nicht als Ziel für einen automatischen Cache-Breakpoint geeignet ist, geht das System stillschweigend rückwärts, um den nächstgelegenen geeigneten Block zu finden. Wenn keiner gefunden wird, wird das Caching übersprungen.



Explizite Cache-Breakpoints

Für mehr Kontrolle über das Caching kannst du cache_control direkt auf einzelnen Content-Blöcken platzieren. Dies ist nützlich, wenn du verschiedene Abschnitte cachen musst, die sich mit unterschiedlicher Häufigkeit ändern, oder wenn du eine feingranulare Kontrolle darüber benötigst, was genau gecacht wird.



Strukturierung deines Prompts

Platziere statischen Inhalt (Tool-Definitionen, Systemanweisungen, Kontext, Beispiele) am Anfang deines Prompts. Markiere das Ende des wiederverwendbaren Inhalts für das Caching mit dem cache_control-Parameter.

Cache-Präfixe werden in der folgenden Reihenfolge erstellt: tools, system, dann messages. Diese Reihenfolge bildet eine Hierarchie, in der jede Ebene auf den vorherigen aufbaut.



So funktioniert die automatische Präfix-Prüfung

Du kannst nur einen Cache-Breakpoint am Ende deines statischen Inhalts verwenden, und das System findet automatisch das längste Präfix, das eine frühere Anfrage bereits in den Cache geschrieben hat. Zu verstehen, wie das funktioniert, hilft dir, deine Caching-Strategie zu optimieren.

Drei Grundprinzipien:

1. Cache-Writes erfolgen nur an deinem Breakpoint. Das Markieren eines Blocks mit cache_control schreibt genau einen Cache-Eintrag: einen Hash des Präfixes, das an diesem Block endet. Das System schreibt keine Einträge für frühere Positionen. Da der Hash kumulativ ist und alles bis einschließlich des Breakpoints abdeckt, erzeugt das Ändern eines beliebigen Blocks an oder vor dem Breakpoint bei der nächsten Anfrage einen anderen Hash.

2. Cache-Reads suchen rückwärts nach Einträgen, die frühere Anfragen geschrieben haben. Bei jeder Anfrage berechnet das System den Präfix-Hash an deinem Breakpoint und prüft auf einen passenden Cache-Eintrag. Wenn keiner existiert, geht es Block für Block rückwärts und prüft, ob der Präfix-Hash an jeder früheren Position mit etwas übereinstimmt, das bereits im Cache ist. Es sucht nach früheren Writes, nicht nach stabilem Inhalt.

3. Das Lookback-Fenster umfasst 20 Blöcke. Das System prüft höchstens 20 Positionen pro Breakpoint, wobei der Breakpoint selbst als erste zählt. Wenn das System in diesem Fenster keinen passenden Eintrag findet, stoppt die Prüfung (oder wird ab dem nächsten expliziten Breakpoint fortgesetzt, falls vorhanden).

Beispiel: Lookback in einer wachsenden Konversation

Du hängst bei jedem Turn neue Blöcke an und setzt cache_control auf den letzten Block jeder Anfrage:

• Turn 1: 10 Blöcke, Breakpoint auf Block 10. Es existieren keine früheren Cache-Einträge. Das System schreibt einen Eintrag bei Block 10.
• Turn 2: 15 Blöcke, Breakpoint auf Block 15. Block 15 hat keinen Eintrag, also geht das System zurück zu Block 10 und findet den Eintrag von Turn 1. Cache-Hit bei Block 10; das System verarbeitet nur die Blöcke 11 bis 15 neu und schreibt einen neuen Eintrag bei Block 15.
• Turn 3: 35 Blöcke, Breakpoint auf Block 35. Das System prüft 20 Positionen (Blöcke 35 bis 16) und findet nichts. Der Eintrag von Turn 2 bei Block 15 liegt eine Position außerhalb des Fensters, also gibt es keinen Cache-Hit. Das Hinzufügen eines zweiten Breakpoints bei Block 15 startet dort ein zweites Lookback-Fenster, das den Eintrag von Turn 2 findet.

Häufiger Fehler: Breakpoint auf Inhalt, der sich bei jeder Anfrage ändert

Dein Prompt hat einen großen statischen Systemkontext (Blöcke 1 bis 5), gefolgt von einem Block pro Anfrage, der einen Zeitstempel und die Benutzernachricht enthält (Block 6). Du setzt cache_control auf Block 6:

• Anfrage 1: Cache-Write bei Block 6. Der Hash enthält den Zeitstempel.
• Anfrage 2: Der Zeitstempel unterscheidet sich, also unterscheidet sich der Präfix-Hash bei Block 6. Der Lookback geht durch die Blöcke 5, 4, 3, 2 und 1, aber das System hat an keiner dieser Positionen jemals einen Eintrag geschrieben. Kein Cache-Hit. Du zahlst bei jeder Anfrage für einen neuen Cache-Write und bekommst nie einen Read.

Der Lookback findet keinen stabilen Inhalt hinter deinem Breakpoint und cacht ihn. Er findet Einträge, die frühere Anfragen bereits geschrieben haben, und Writes erfolgen nur an Breakpoints. Verschiebe cache_control auf Block 5, den letzten Block, der über Anfragen hinweg gleich bleibt, und jede nachfolgende Anfrage liest das gecachte Präfix. Automatisches Caching tappt in dieselbe Falle: Es platziert den Breakpoint auf dem letzten cachefähigen Block, der in dieser Struktur derjenige ist, der sich bei jeder Anfrage ändert – verwende daher stattdessen einen expliziten Breakpoint auf Block 5.

Wichtigste Erkenntnis: Platziere cache_control auf dem letzten Block, dessen Präfix über die Anfragen hinweg identisch ist, die sich einen Cache teilen sollen. In einer wachsenden Konversation funktioniert der letzte Block, solange jeder Turn weniger als 20 Blöcke hinzufügt: Früherer Inhalt ändert sich nie, sodass der Lookback der nächsten Anfrage den vorherigen Write findet. Bei einem Prompt mit einem variierenden Suffix (Zeitstempel, anfragespezifischer Kontext, die eingehende Nachricht) platziere den Breakpoint am Ende des statischen Präfixes, nicht auf dem variierenden Block.



Wann mehrere Breakpoints verwendet werden sollten

Du kannst bis zu 4 Cache-Breakpoints definieren, wenn du:

• Verschiedene Abschnitte cachen möchtest, die sich mit unterschiedlicher Häufigkeit ändern (zum Beispiel ändern sich Tools selten, aber der Kontext wird täglich aktualisiert)
• Mehr Kontrolle darüber haben möchtest, was genau gecacht wird
• Einen Cache-Hit sicherstellen möchtest, wenn eine wachsende Konversation deinen Breakpoint 20 oder mehr Blöcke über den letzten Cache-Write hinaus verschiebt



Kosten von Cache-Breakpoints verstehen

Cache-Breakpoints selbst verursachen keine zusätzlichen Kosten. Dir wird nur Folgendes berechnet:

• Cache-Writes: Wenn neuer Inhalt in den Cache geschrieben wird (25 % mehr als Basis-Input-Token für 5-Minuten-TTL)
• Cache-Reads: Wenn gecachter Inhalt verwendet wird (10 % des Basispreises für Input-Token)
• Reguläre Input-Token: Für jeglichen nicht gecachten Inhalt

Das Hinzufügen weiterer cache_control-Breakpoints erhöht deine Kosten nicht – du zahlst weiterhin denselben Betrag basierend darauf, welcher Inhalt tatsächlich gecacht und gelesen wird. Die Breakpoints geben dir Kontrolle darüber, welche Abschnitte unabhängig voneinander gecacht werden können.



Caching-Strategien und Überlegungen



Cache-Einschränkungen

Auf der Claude API, Claude Platform on AWS, Google Cloud und Microsoft Foundry beträgt die minimale cachefähige Prompt-Länge:

• 512 Token für Claude Opus 5, Claude Fable 5 und Claude Mythos 5
• 2.048 Token für Claude Mythos Preview und Claude Opus 4.7
• 4.096 Token für Claude Opus 4.6 und Claude Opus 4.5
• 1.024 Token für Claude Opus 4.8, Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Opus 4.1 (eingestellt, außer auf Bedrock und Google Cloud), Claude Opus 4 (eingestellt, außer auf Google Cloud) und Claude Sonnet 4 (eingestellt, außer auf Bedrock und Google Cloud)
• 4.096 Token für Claude Haiku 4.5
• 2.048 Token für Claude Haiku 3.5 (eingestellt, außer auf Bedrock und Google Cloud)

Diese Mindestwerte gelten auf jeder Plattform, auf der das jeweilige Modell verfügbar ist.

Kürzere Prompts können nicht gecacht werden, selbst wenn sie mit cache_control markiert sind. Alle Anfragen zum Cachen von weniger als dieser Anzahl von Token werden ohne Caching verarbeitet, und es wird kein Fehler zurückgegeben. Um zu überprüfen, ob ein Prompt gecacht wurde, prüfe die Usage-Felder in der Antwort: Wenn sowohl cache_creation_input_tokens als auch cache_read_input_tokens 0 sind, wurde der Prompt nicht gecacht (wahrscheinlich, weil er die Mindestlängenanforderung nicht erfüllt hat).

Wenn dein Prompt knapp unter dem Minimum für dein Modell und deine Plattform liegt, lohnt es sich oft, den gecachten Inhalt zu erweitern, um den Schwellenwert zu erreichen. Cache-Reads kosten deutlich weniger als nicht gecachte Input-Token, sodass das Erreichen des Minimums die Kosten für häufig wiederverwendete Prompts senken kann.

Bei gleichzeitigen Anfragen ist zu beachten, dass ein Cache-Eintrag erst verfügbar wird, nachdem die erste Antwort begonnen hat. Wenn du Cache-Hits für parallele Anfragen benötigst, warte auf die erste Antwort, bevor du nachfolgende Anfragen sendest.

Derzeit ist „ephemeral" der einzige unterstützte Cache-Typ, der standardmäßig eine Lebensdauer von 5 Minuten hat.



Was gecacht werden kann

Die meisten Blöcke in der Anfrage können gecacht werden. Dazu gehören:

• Tools: Tool-Definitionen im tools-Array
• Systemnachrichten: Content-Blöcke im system-Array
• Textnachrichten: Content-Blöcke im messages.content-Array, sowohl für User- als auch Assistant-Turns
• Bilder & Dokumente: Content-Blöcke im messages.content-Array, in User-Turns
• Tool-Nutzung und Tool-Ergebnisse: Content-Blöcke im messages.content-Array, sowohl in User- als auch Assistant-Turns

Jedes dieser Elemente kann gecacht werden, entweder automatisch oder durch Markierung mit cache_control.



Was nicht gecacht werden kann

Während die meisten Request-Blöcke gecacht werden können, gibt es einige Ausnahmen:

• Thinking-Blöcke können nicht direkt mit cache_control gecacht werden. Thinking-Blöcke KÖNNEN jedoch zusammen mit anderem Inhalt gecacht werden, wenn sie in vorherigen Assistant-Turns erscheinen. Wenn sie auf diese Weise gecacht werden, ZÄHLEN sie als Input-Token, wenn sie aus dem Cache gelesen werden.

• Sub-Content-Blöcke (wie Zitate) selbst können nicht direkt gecacht werden. Cache stattdessen den übergeordneten Block.

  Im Fall von Zitaten können die übergeordneten Dokument-Content-Blöcke, die als Quellmaterial für Zitate dienen, gecacht werden. Dies ermöglicht es dir, Prompt-Caching effektiv mit Zitaten zu verwenden, indem du die Dokumente cachst, auf die Zitate verweisen werden.

• Leere Textblöcke können nicht gecacht werden.



Was den Cache invalidiert

Änderungen an gecachtem Inhalt können einen Teil oder den gesamten Cache invalidieren.

Wie in Strukturierung deines Prompts beschrieben, folgt der Cache der Hierarchie: tools → system → messages. Änderungen auf jeder Ebene invalidieren diese Ebene und alle nachfolgenden Ebenen.

Die folgende Tabelle zeigt, welche Teile des Caches durch verschiedene Arten von Änderungen invalidiert werden. ✘ zeigt an, dass der Cache invalidiert wird, während ✓ anzeigt, dass der Cache gültig bleibt.



Cache-Performance verfolgen

Überwache die Cache-Performance mit diesen API-Antwortfeldern innerhalb von usage in der Antwort (oder im message_start-Event bei Streaming):

• cache_creation_input_tokens: Anzahl der Token, die beim Erstellen eines neuen Eintrags in den Cache geschrieben wurden.
• cache_read_input_tokens: Anzahl der Token, die für diese Anfrage aus dem Cache abgerufen wurden.
• input_tokens: Anzahl der Input-Token, die nicht aus dem Cache gelesen oder zum Erstellen eines Caches verwendet wurden (das heißt, Token nach dem letzten Cache-Breakpoint).



Caching mit Thinking-Blöcken

Bei der Verwendung von Thinking mit Prompt-Caching haben Thinking-Blöcke ein besonderes Verhalten:

Automatisches Caching zusammen mit anderem Inhalt: Während Thinking-Blöcke nicht explizit mit cache_control markiert werden können, werden sie als Teil des Anfrageinhalts gecacht, wenn du nachfolgende API-Aufrufe mit Tool-Ergebnissen machst. Dies geschieht häufig bei der Tool-Nutzung, wenn du Thinking-Blöcke zurückgibst, um die Konversation fortzusetzen.

Input-Token-Zählung: Wenn Thinking-Blöcke aus dem Cache gelesen werden, zählen sie als Input-Token in deinen Nutzungsmetriken. Dies ist wichtig für die Kostenberechnung und Token-Budgetierung.

Cache-Invalidierungsmuster:

• Der Cache bleibt gültig, wenn nur Tool-Ergebnisse als Benutzernachrichten bereitgestellt werden
• Bei Opus 4.5+ und Sonnet 4.6+ werden Thinking-Blöcke standardmäßig beibehalten, auch wenn Nicht-Tool-Result-Benutzerinhalt hinzugefügt wird, sodass der Cache gültig bleibt
• Bei früheren Opus/Sonnet-Modellen und allen Haiku-Modellen wird der Cache invalidiert, wenn Nicht-Tool-Result-Benutzerinhalt hinzugefügt wird, wodurch alle vorherigen Thinking-Blöcke aus dem Kontext entfernt werden
• Dieses Caching-Verhalten tritt auch ohne explizite cache_control-Markierungen auf

Weitere Details zur Cache-Invalidierung findest du unter Was den Cache invalidiert.

Beispiel mit Tool-Nutzung:

Request 1: User: "What's the weather in Paris?"
Response: [thinking_block_1] + [tool_use block 1]

Request 2:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True]
Response: [thinking_block_2] + [text block 2]
# Request 2 caches its request content (not the response)
# The cache includes: user message, thinking_block_1, tool_use block 1, and tool_result_1

Request 3:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]
# On earlier Opus/Sonnet and all Haiku models, non-tool-result user block causes prior thinking blocks to be stripped; on Opus 4.5+/Sonnet 4.6+ they are kept

Bei früheren Opus/Sonnet-Modellen und allen Haiku-Modellen werden an diesem Punkt alle vorherigen Thinking-Blöcke aus dem Kontext entfernt. Bei Opus 4.5+ und Sonnet 4.6+ werden frühere Thinking-Blöcke standardmäßig beibehalten und bleiben Teil des gecachten Präfixes.

Ausführlichere Informationen findest du unter Thinking und Prompt-Caching.



Cache-Speicherung und -Freigabe

• Organisations- und Workspace-Isolation: Caches sind zwischen Organisationen isoliert. Verschiedene Organisationen teilen niemals Caches, selbst wenn sie identische Prompts verwenden. Caches sind auch pro Workspace innerhalb einer Organisation auf der Claude API, Claude Platform on AWS und Microsoft Foundry isoliert; Bedrock und Google Cloud verwenden nur Isolation auf Organisationsebene.

• Exakte Übereinstimmung: Cache-Hits erfordern 100 % identische Prompt-Segmente, einschließlich aller Texte und Bilder bis einschließlich des mit cache_control markierten Blocks.

• Output-Token-Generierung: Prompt-Caching hat keine Auswirkung auf die Output-Token-Generierung. Die Antwort, die du erhältst, ist identisch mit dem, was du erhalten würdest, wenn Prompt-Caching nicht verwendet würde.



Best Practices für effektives Caching

Um die Prompt-Caching-Performance zu optimieren:

• Beginne mit automatischem Caching für mehrstufige Konversationen. Es übernimmt die Breakpoint-Verwaltung automatisch.
• Verwende explizite Block-Level-Breakpoints, wenn du verschiedene Abschnitte mit unterschiedlichen Änderungshäufigkeiten cachen musst.
• Cache stabilen, wiederverwendbaren Inhalt wie Systemanweisungen, Hintergrundinformationen, große Kontexte oder häufige Tool-Definitionen.
• Platziere gecachten Inhalt am Anfang des Prompts für beste Performance.
• Verwende Cache-Breakpoints strategisch, um verschiedene cachefähige Präfix-Abschnitte zu trennen.
• Platziere den Breakpoint auf dem letzten Block, der über Anfragen hinweg identisch bleibt. Bei einem Prompt mit einem statischen Präfix und einem variierenden Suffix (Zeitstempel, anfragespezifischer Kontext, die eingehende Nachricht) ist das das Ende des Präfixes, nicht der variierende Block.
• Analysiere regelmäßig Cache-Hit-Raten und passe deine Strategie bei Bedarf an.



Optimierung für verschiedene Anwendungsfälle

Passe deine Prompt-Caching-Strategie an dein Szenario an:

• Konversationsagenten: Reduziere Kosten und Latenz für längere Konversationen, insbesondere solche mit langen Anweisungen oder hochgeladenen Dokumenten.
• Coding-Assistenten: Verbessere Autovervollständigung und Codebase-Q&A, indem du relevante Abschnitte oder eine zusammengefasste Version der Codebase im Prompt behältst.
• Verarbeitung großer Dokumente: Integriere vollständiges Langform-Material einschließlich Bildern in deinen Prompt, ohne die Antwortlatenz zu erhöhen.
• Detaillierte Anweisungssätze: Teile umfangreiche Listen von Anweisungen, Verfahren und Beispielen, um Claudes Antworten zu verfeinern. Entwickler fügen oft ein oder zwei Beispiele in den Prompt ein, aber mit Prompt-Caching kannst du noch bessere Performance erzielen, indem du 20+ vielfältige Beispiele hochwertiger Antworten einbeziehst.
• Agentische Tool-Nutzung: Verbessere die Performance für Szenarien mit mehreren Tool-Aufrufen und iterativen Code-Änderungen, bei denen jeder Schritt typischerweise einen neuen API-Aufruf erfordert.
• Mit Büchern, Papers, Dokumentation, Podcast-Transkripten und anderem Langform-Inhalt sprechen: Erwecke jede Wissensbasis zum Leben, indem du das gesamte Dokument bzw. die gesamten Dokumente in den Prompt einbettest und Benutzer Fragen dazu stellen lässt.



Fehlerbehebung bei häufigen Problemen

Bei unerwartetem Verhalten:

• Stelle sicher, dass gecachte Abschnitte über Aufrufe hinweg identisch sind. Bei expliziten Breakpoints überprüfe, dass cache_control-Markierungen an denselben Stellen sind
• Prüfe, ob Aufrufe innerhalb der Cache-Lebensdauer erfolgen (standardmäßig 5 Minuten)
• Überprüfe, dass tool_choice, Bildnutzung, die Thinking-Konfiguration und output_config.effort zwischen Aufrufen konsistent bleiben
• Validiere, dass du mindestens die Mindestanzahl von Token für dein Modell und deine Plattform cachst (siehe Cache-Einschränkungen)
• Bestätige, dass dein Breakpoint auf einem Block liegt, der über Anfragen hinweg identisch bleibt. Cache-Writes erfolgen nur am Breakpoint, und wenn sich dieser Block ändert (Zeitstempel, anfragespezifischer Kontext, die eingehende Nachricht), stimmt der Präfix-Hash nie überein. Der Lookback findet keinen stabilen Inhalt hinter dem Breakpoint; er findet nur Einträge, die frühere Anfragen an ihren eigenen Breakpoints geschrieben haben
• Überprüfe, dass die Schlüssel in deinen tool_use-Content-Blöcken eine stabile Reihenfolge haben, da einige Sprachen (zum Beispiel Swift, Go) die Schlüsselreihenfolge während der JSON-Konvertierung randomisieren, was Caches bricht
• Verwende Cache-Diagnose, um die API aufeinanderfolgende Anfragen vergleichen und melden zu lassen, welcher Teil des Prompts abgewichen ist



1-Stunden-Cache-Dauer

Wenn dir 5 Minuten zu kurz sind, bietet Anthropic auch eine 1-Stunden-Cache-Dauer gegen zusätzliche Kosten an.

Um den erweiterten Cache zu verwenden, füge ttl in die cache_control-Definition wie folgt ein:

"cache_control": {
  "type": "ephemeral",
  "ttl": "1h"
}

Die Antwort enthält detaillierte Cache-Informationen wie die folgenden:

{
  "usage": {
    "input_tokens": 2048,
    "cache_read_input_tokens": 1800,
    "cache_creation_input_tokens": 248,
    "output_tokens": 503,

    "cache_creation": {
      "ephemeral_5m_input_tokens": 148,
      "ephemeral_1h_input_tokens": 100
    }
  }
}

Beachte, dass das aktuelle cache_creation_input_tokens-Feld der Summe der Werte im cache_creation-Objekt entspricht.

Wenn du ephemeral_5m_input_tokens-Writes siehst, die du nicht angefordert hast, während du Server-Tools wie die Websuche verwendest, siehe Tool-Nutzung mit Prompt-Caching.



Wann der 1-Stunden-Cache verwendet werden sollte

Wenn du Prompts hast, die in regelmäßigen Abständen verwendet werden (das heißt, System-Prompts, die häufiger als alle 5 Minuten verwendet werden), verwende weiterhin den 5-Minuten-Cache, da dieser ohne zusätzliche Kosten weiterhin aktualisiert wird.

Der 1-Stunden-Cache wird am besten in den folgenden Szenarien verwendet:

• Wenn du Prompts hast, die wahrscheinlich seltener als alle 5 Minuten, aber häufiger als jede Stunde verwendet werden. Zum Beispiel, wenn ein agentischer Side-Agent länger als 5 Minuten braucht, oder wenn du eine lange Chat-Konversation mit einem Benutzer speicherst und generell erwartest, dass dieser Benutzer möglicherweise nicht in den nächsten 5 Minuten antwortet.
• Wenn Latenz wichtig ist und deine Folge-Prompts möglicherweise nach mehr als 5 Minuten gesendet werden.
• Wenn du deine Ratenlimit-Auslastung verbessern möchtest, da Cache-Hits nicht von deinem Ratenlimit abgezogen werden.



Mischen verschiedener TTLs

Du kannst sowohl 1-Stunden- als auch 5-Minuten-Cache-Controls in derselben Anfrage verwenden, aber mit einer wichtigen Einschränkung: Cache-Einträge mit längerer TTL müssen vor kürzeren TTLs erscheinen (das heißt, ein 1-Stunden-Cache-Eintrag muss vor allen 5-Minuten-Cache-Einträgen erscheinen).

Beim Mischen von TTLs bestimmt die API drei Abrechnungspositionen in deinem Prompt:

1. Position A: Die Token-Anzahl beim höchsten Cache-Hit (oder 0, wenn keine Hits).
2. Position B: Die Token-Anzahl beim höchsten 1-Stunden-cache_control-Block nach A (oder gleich A, wenn keiner existiert).
3. Position C: Die Token-Anzahl beim letzten cache_control-Block.

Dir wird Folgendes berechnet:

1. Cache-Read-Token für A.
2. 1-Stunden-Cache-Write-Token für (B - A).
3. 5-Minuten-Cache-Write-Token für (C - B).

Hier sind drei Beispiele. Dies zeigt die Input-Token von 3 Anfragen, von denen jede unterschiedliche Cache-Hits und Cache-Misses hat. Jede hat eine unterschiedlich berechnete Preisgestaltung, die in den farbigen Kästchen dargestellt ist.



Vorwärmen des Caches

Cache-Vorwärmen ermöglicht es dir, deinen System-Prompt oder deine Tool-Definitionen in den Prompt-Cache zu laden, bevor ein Benutzer eine echte Anfrage auslöst. Dies eliminiert die Cache-Miss-Latenzstrafe bei der ersten Benutzerinteraktion und reduziert die „time-to-first-token" (Zeit bis zum ersten Token), oder TTFT, für latenzempfindliche Anwendungen.



Funktionsweise

Setze max_tokens: 0 in deiner Anfrage. Die API liest deinen Prompt in das Modell ein und schreibt den Cache an jedem cache_control-Breakpoint, gibt dann sofort zurück, ohne eine Ausgabe zu generieren. Die Antwort hat ein leeres content-Array, stop_reason: "max_tokens" und einen vollständig ausgefüllten usage-Block.

Platziere den cache_control-Breakpoint auf dem letzten Block, der mit der Folgeanfrage geteilt wird (typischerweise dein System-Prompt oder deine Tool-Definitionen), nicht auf der Platzhalter-User-Nachricht. Andernfalls wird der Cache-Eintrag an den Platzhalter gebunden und die Folgeanfrage wird ihn nicht treffen. Verwende auch dieselbe Thinking-Konfiguration und denselben output_config.effort wie deine Folgeanfragen: Diese Werte werden in den Prompt gerendert (siehe Was den Cache ungültig macht), sodass ein Pre-Warm mit einer anderen Konfiguration einen Eintrag schreiben kann, den dein echter Traffic nie trifft. Das bedeutet, dass du einen expliziten Cache-Breakpoint anstelle von automatischem Caching verwenden solltest, da automatisches Caching den Breakpoint auf den letzten Block setzt, der hier der Platzhalter ist. Die Platzhalter-User-Nachricht kann ein beliebiger String mit Nicht-Whitespace-Inhalt sein (die Beispiele hier verwenden "warmup"); ihr Inhalt wird in das Modell eingelesen, aber nie beantwortet.

client = anthropic.Anthropic()

# Führe dies aus, bevor Nutzer eintreffen, um den gemeinsamen System-Prompt-Cache vorzuwärmen.
prewarm = client.messages.create(
    model="claude-opus-5",
    max_tokens=0,
    system=[
        {
            "type": "text",
            "text": "You are an expert software engineer with deep knowledge of distributed systems...",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "warmup"}],
)
print(prewarm.stop_reason)  # "max_tokens"
print(prewarm.content)  # []
print(prewarm.usage)

Die API gibt ein leeres content-Array zurück:

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [],
  "model": "claude-opus-5",
  "stop_reason": "max_tokens",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 8,
    "cache_creation_input_tokens": 5120,
    "cache_read_input_tokens": 0,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 5120,
      "ephemeral_1h_input_tokens": 0
    },
    "iterations": [
      {
        "input_tokens": 8,
        "output_tokens": 0,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 5120,
        "cache_creation": {
          "ephemeral_5m_input_tokens": 5120,
          "ephemeral_1h_input_tokens": 0
        },
        "type": "message"
      }
    ],
    "output_tokens": 0,
    "service_tier": "standard",
    "inference_geo": "global"
  }
}



Typisches Nutzungsmuster

Sende eine Pre-Warm-Anfrage, wenn deine Anwendung startet (oder in einem geplanten Intervall), und sende dann echte User-Anfragen, nachdem das Pre-Warm abgeschlossen ist:

client = anthropic.Anthropic()

SYSTEM_PROMPT = [
    {
        "type": "text",
        "text": "You are an expert software engineer with deep knowledge of distributed systems...",
        "cache_control": {"type": "ephemeral"},
    }
]


def prewarm_cache() -> None:
    """Call this at application startup or on a scheduled interval."""
    client.messages.create(
        model="claude-opus-5",
        max_tokens=0,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": "warmup"}],
    )


def respond(user_message: str) -> anthropic.types.Message:
    """The real user request; benefits from a warm cache."""
    return client.messages.create(
        model="claude-opus-5",
        max_tokens=1024,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": user_message}],
    )


# Wärme den Cache auf, bevor Nutzer-Traffic eintrifft.
prewarm_cache()

# Später, wenn der Nutzer eine Nachricht sendet, ist das System-Prompt-Präfix bereits gecacht.
response = respond("How do I implement a binary search tree?")
for block in response.content:
    if block.type == "text":
        print(block.text)

Beachte, dass die Cache-TTL weiterhin gilt. Für den standardmäßigen 5-Minuten-Cache sende mindestens alle 5 Minuten eine neue Pre-Warm-Anfrage, um den Cache warm zu halten. Für längere Abstände zwischen User-Anfragen verwende stattdessen die 1-Stunden-Cache-Dauer.



Einschränkungen

Eine max_tokens: 0-Anfrage wird mit einem invalid_request_error abgelehnt, wenn eine der folgenden Optionen gesetzt ist, da jede davon eine Ausgabe impliziert, die ein Null-Token-Budget nicht erzeugen kann:

• stream: true
• Erweitertes Denken (thinking.type: "enabled")
• Strukturierte Ausgaben (output_config.format)
• tool_choice mit {"type": "tool", ...} oder {"type": "any"}

max_tokens: 0 wird auch innerhalb einer Message Batches-Anfrage abgelehnt. Pre-Warming zielt auf die Time-to-First-Token ab, was für Batch-Verarbeitung nicht relevant ist, und ein während der Batch-Verarbeitung geschriebener Cache-Eintrag würde wahrscheinlich ablaufen, bevor die Folgeanfrage ausgeführt wird.



Ersetzen des max_tokens=1-Workarounds

Bevor max_tokens: 0 verfügbar war, verwendeten einige Anwendungen max_tokens: 1-Warm-up-Aufrufe, um denselben Effekt zu erzielen. Der max_tokens: 0-Ansatz wird bevorzugt: Es wird keine Ausgabe erzeugt, sodass es keine Ein-Token-Antwort zum Verwerfen gibt, keine Output-Token berechnet werden und die Absicht der Anfrage eindeutig ist.



Prompt-Caching-Beispiele

Um dir den Einstieg in Prompt-Caching zu erleichtern, bietet das Prompt-Caching-Cookbook detaillierte Beispiele und Best Practices.

Die folgenden Code-Snippets zeigen verschiedene Prompt-Caching-Muster. Diese Beispiele demonstrieren, wie du Caching in verschiedenen Szenarien implementierst, und helfen dir, die praktischen Anwendungen dieser Funktion zu verstehen:



Datenspeicherung

Prompt-Caching (sowohl automatisch als auch explizit) ist ZDR-fähig. Anthropic speichert nicht den Rohtext deiner Prompts oder die Antworten von Claude.

KV-Cache-Repräsentationen (Key-Value) und kryptografische Hashes von gecachten Inhalten werden nur im Arbeitsspeicher gehalten und nicht dauerhaft gespeichert. Gecachte Einträge haben eine Mindestlebensdauer von 5 Minuten (Standard) oder 1 Stunde (erweitert), nach der sie zeitnah, wenn auch nicht sofort, gelöscht werden. Cache-Einträge sind zwischen Organisationen isoliert und, auf der Claude API, Claude Platform on AWS und Microsoft Foundry, zwischen Workspaces innerhalb einer Organisation.

Für ZDR-Fähigkeit über alle Funktionen hinweg siehe API und Datenspeicherung.



FAQ