Was this page helpful?
Prompt-Caching ist eine leistungsstarke Funktion, die Ihre API-Nutzung optimiert, indem Sie von bestimmten Präfixen in Ihren Prompts fortfahren können. Dieser Ansatz reduziert die Verarbeitungszeit und Kosten für wiederholte Aufgaben oder Prompts mit konsistenten Elementen erheblich.
Prompt-Caching speichert KV-Cache-Darstellungen und kryptografische Hashes von zwischengespeicherten Inhalten, speichert aber nicht den Rohtext von Prompts oder Antworten. Dies kann für Kunden geeignet sein, die ZDR-ähnliche Datenspeicherungsverpflichtungen benötigen. Siehe Cache-Lebensdauer für Details.
Hier ist ein Beispiel für die Implementierung von Prompt-Caching mit der Messages API unter Verwendung eines cache_control-Blocks:
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-4-6",
"max_tokens": 1024,
"system": [
{
"type": "text",
"text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
},
{
"type": "text",
"text": "<the entire contents of Pride and Prejudice>",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [
{
"role": "user",
"content": "Analyze the major themes in Pride and Prejudice."
}
]
}'
# Call the model again with the same inputs up to the cache checkpoint
curl https://api.anthropic.com/v1/messages # rest of input{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}In diesem Beispiel wird der gesamte Text von „Pride and Prejudice" mit dem cache_control-Parameter zwischengespeichert. Dies ermöglicht die Wiederverwendung dieses großen Textes über mehrere API-Aufrufe hinweg, ohne ihn jedes Mal neu zu verarbeiten. Wenn Sie nur die Benutzermeldung ändern, können Sie verschiedene Fragen zum Buch stellen und dabei den zwischengespeicherten Inhalt nutzen, was zu schnelleren Antworten und verbesserter Effizienz führt.
Wenn Sie eine Anfrage mit aktiviertem Prompt-Caching senden:
Dies ist besonders nützlich für:
Standardmäßig hat der Cache eine Lebensdauer von 5 Minuten. Der Cache wird jedes Mal, wenn der zwischengespeicherte Inhalt verwendet wird, kostenlos aktualisiert.
Wenn Sie feststellen, dass 5 Minuten zu kurz sind, bietet Anthropic auch eine Cache-Dauer von 1 Stunde gegen zusätzliche Kosten an.
Weitere Informationen finden Sie unter Cache-Dauer von 1 Stunde.
Prompt-Caching speichert das vollständige Präfix zwischen
Prompt-Caching verweist auf den gesamten Prompt - tools, system und messages (in dieser Reihenfolge) bis zu und einschließlich des Blocks, der mit cache_control gekennzeichnet ist.
Prompt-Caching führt eine neue Preisstruktur ein. Die folgende Tabelle zeigt den Preis pro Million Token für jedes unterstützte Modell:
| Model | Base Input Tokens | 5m Cache Writes | 1h Cache Writes | Cache Hits & Refreshes | Output Tokens |
|---|---|---|---|---|---|
| Claude Opus 4.6 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.5 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.1 | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Opus 4 | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Sonnet 4.6 |
Die obige Tabelle spiegelt die folgenden Preismultiplikatoren für Prompt-Caching wider:
Diese Multiplikatoren stapeln sich mit anderen Preismodifiern wie dem Batch-API-Rabatt, der Langkontext-Preisgestaltung und der Datenresidenz. Siehe Preisgestaltung für vollständige Details.
Prompt-Caching wird derzeit unterstützt auf:
Platzieren Sie statische Inhalte (Tool-Definitionen, Systemanweisungen, Kontext, Beispiele) am Anfang Ihres Prompts. Markieren Sie das Ende des wiederverwendbaren Inhalts zum Zwischenspeichern mit dem cache_control-Parameter.
Cache-Präfixe werden in der folgenden Reihenfolge erstellt: tools, system, dann messages. Diese Reihenfolge bildet eine Hierarchie, bei der jede Ebene auf den vorherigen aufbaut.
Sie können nur einen Cache-Haltepunkt am Ende Ihres statischen Inhalts verwenden, und das System findet automatisch die längste übereinstimmende Sequenz von zwischengespeicherten Blöcken. Das Verständnis, wie dies funktioniert, hilft Ihnen, Ihre Caching-Strategie zu optimieren.
Drei Kernprinzipien:
Cache-Schlüssel sind kumulativ: Wenn Sie einen Block explizit mit cache_control zwischenspeichern, wird der Cache-Hash-Schlüssel durch Hashing aller vorherigen Blöcke in der Konversation sequenziell generiert. Dies bedeutet, dass der Cache für jeden Block von allen Inhalten abhängt, die davor kamen.
Rückwärts-sequenzielle Überprüfung: Das System prüft auf Cache-Treffer, indem es rückwärts von Ihrem expliziten Haltepunkt arbeitet und jeden vorherigen Block in umgekehrter Reihenfolge überprüft. Dies stellt sicher, dass Sie den längstmöglichen Cache-Treffer erhalten.
20-Block-Lookback-Fenster: Das System prüft nur bis zu 20 Blöcke vor jedem expliziten cache_control-Haltepunkt. Nach 20 Überprüfungen ohne Übereinstimmung stoppt es die Überprüfung und wechselt zum nächsten expliziten Haltepunkt (falls vorhanden).
Beispiel: Das Lookback-Fenster verstehen
Betrachten Sie eine Konversation mit 30 Inhaltsblöcken, bei der Sie cache_control nur auf Block 30 setzen:
Wenn Sie Block 31 ohne Änderungen an vorherigen Blöcken senden: Das System prüft Block 30 (Treffer!). Sie erhalten einen Cache-Treffer bei Block 30, und nur Block 31 muss verarbeitet werden.
Wenn Sie Block 25 ändern und Block 31 senden: Das System prüft rückwärts von Block 30 → 29 → 28... → 25 (kein Treffer) → 24 (Treffer!). Da Block 24 nicht geändert wurde, erhalten Sie einen Cache-Treffer bei Block 24, und nur die Blöcke 25-30 müssen neu verarbeitet werden.
Wenn Sie Block 5 ändern und Block 31 senden: Das System prüft rückwärts von Block 30 → 29 → 28... → 11 (Überprüfung #20). Nach 20 Überprüfungen ohne Übereinstimmung stoppt es die Suche. Da Block 5 außerhalb des 20-Block-Fensters liegt, tritt kein Cache-Treffer auf und alle Blöcke müssen neu verarbeitet werden. Wenn Sie jedoch einen expliziten cache_control-Haltepunkt auf Block 5 gesetzt hätten, würde das System die Überprüfung von diesem Haltepunkt aus fortsetzen: Block 5 (kein Treffer) → Block 4 (Treffer!). Dies ermöglicht einen Cache-Treffer bei Block 4, was zeigt, warum Sie Haltepunkte vor bearbeitbarem Inhalt platzieren sollten.
Wichtigste Erkenntnis: Setzen Sie immer einen expliziten Cache-Haltepunkt am Ende Ihrer Konversation, um Ihre Chancen auf Cache-Treffer zu maximieren. Setzen Sie zusätzlich Haltepunkte direkt vor Inhaltsblöcken, die bearbeitet werden könnten, um sicherzustellen, dass diese Abschnitte unabhängig zwischengespeichert werden können.
Sie können bis zu 4 Cache-Haltepunkte definieren, wenn Sie möchten:
Wichtige Einschränkung: Wenn Ihr Prompt mehr als 20 Inhaltsblöcke vor Ihrem Cache-Haltepunkt hat und Sie Inhalte ändern, die früher als diese 20 Blöcke liegen, erhalten Sie keinen Cache-Treffer, es sei denn, Sie fügen zusätzliche explizite Haltepunkte näher an diesem Inhalt hinzu.
Die minimale zwischenspeicherbare Prompt-Länge beträgt:
Kürzere Prompts können nicht zwischengespeichert werden, auch wenn sie mit cache_control gekennzeichnet sind. Alle Anfragen zum Zwischenspeichern von weniger als dieser Anzahl von Token werden ohne Caching verarbeitet. Um zu sehen, ob ein Prompt zwischengespeichert wurde, siehe die Antwort-Nutzungs-Felder.
Beachten Sie bei gleichzeitigen Anfragen, dass ein Cache-Eintrag erst verfügbar wird, nachdem die erste Antwort beginnt. Wenn Sie Cache-Treffer für parallele Anfragen benötigen, warten Sie auf die erste Antwort, bevor Sie nachfolgende Anfragen senden.
Derzeit ist „ephemeral" der einzige unterstützte Cache-Typ, der standardmäßig eine Lebensdauer von 5 Minuten hat.
Cache-Haltepunkte selbst verursachen keine Kosten. Sie werden nur belastet für:
Das Hinzufügen weiterer cache_control-Haltepunkte erhöht Ihre Kosten nicht - Sie zahlen immer noch den gleichen Betrag basierend auf dem, was tatsächlich zwischengespeichert und gelesen wird. Die Haltepunkte geben Ihnen einfach Kontrolle darüber, welche Abschnitte unabhängig zwischengespeichert werden können.
Die meisten Blöcke in der Anfrage können mit cache_control zum Zwischenspeichern gekennzeichnet werden. Dies umfasst:
tools-Arraysystem-Arraymessages.content-Array, sowohl für Benutzer- als auch für Assistent-Turnsmessages.content-Array, in Benutzer-Turnsmessages.content-Array, sowohl für Benutzer- als auch für Assistent-TurnsJedes dieser Elemente kann mit cache_control gekennzeichnet werden, um Caching für diesen Teil der Anfrage zu aktivieren.
Während die meisten Anfrage-Blöcke zwischengespeichert werden können, gibt es einige Ausnahmen:
Thinking-Blöcke können nicht direkt mit cache_control zwischengespeichert werden. Thinking-Blöcke KÖNNEN jedoch zusammen mit anderen Inhalten zwischengespeichert werden, wenn sie in vorherigen Assistent-Turns erscheinen. Wenn sie auf diese Weise zwischengespeichert werden, zählen sie als Eingabe-Token, wenn sie aus dem Cache gelesen werden.
Sub-Content-Blöcke (wie Zitate) können nicht direkt zwischengespeichert werden. Speichern Sie stattdessen den Top-Level-Block zwischen.
Im Fall von Zitaten können die Top-Level-Dokumentinhaltsblöcke, die als Quellmaterial für Zitate dienen, zwischengespeichert werden. Dies ermöglicht es Ihnen, Prompt-Caching mit Zitaten effektiv zu nutzen, indem Sie die Dokumente zwischenspeichern, auf die Zitate verweisen.
Leere Textblöcke können nicht zwischengespeichert werden.
Änderungen an zwischengespeicherten Inhalten können einen Teil oder den gesamten Cache ungültig machen.
Wie in Strukturierung Ihres Prompts beschrieben, folgt der Cache der Hierarchie: tools → system → messages. Änderungen auf jeder Ebene machen diese Ebene und alle nachfolgenden Ebenen ungültig.
Die folgende Tabelle zeigt, welche Teile des Cache durch verschiedene Arten von Änderungen ungültig gemacht werden. ✘ zeigt an, dass der Cache ungültig ist, während ✓ anzeigt, dass der Cache gültig bleibt.
| Was ändert sich | Tools-Cache | System-Cache | Messages-Cache | Auswirkung |
|---|---|---|---|---|
| Tool-Definitionen | ✘ | ✘ | ✘ | Das Ändern von Tool-Definitionen (Namen, Beschreibungen, Parameter) macht den gesamten Cache ungültig |
| Web-Suche-Umschalter | ✓ | ✘ | ✘ | Das Aktivieren/Deaktivieren der Web-Suche ändert den System-Prompt |
| Zitate-Umschalter | ✓ | ✘ | ✘ | Das Aktivieren/Deaktivieren von Zitaten ändert den System-Prompt |
| Geschwindigkeitseinstellung | ✓ | ✘ | ✘ | Das Wechseln zwischen speed: "fast" und Standardgeschwindigkeit macht System- und Message-Caches ungültig |
Überwachen Sie die Cache-Leistung mit diesen API-Antwortfeldern, innerhalb von usage in der Antwort (oder message_start-Ereignis bei Streaming):
cache_creation_input_tokens: Anzahl der Token, die beim Erstellen eines neuen Eintrags in den Cache geschrieben werden.cache_read_input_tokens: Anzahl der Token, die für diese Anfrage aus dem Cache abgerufen werden.input_tokens: Anzahl der Eingabe-Token, die nicht aus dem Cache gelesen oder zum Erstellen eines Cache verwendet wurden (d. h. Token nach dem letzten Cache-Haltepunkt).Das Token-Aufschlüsselung verstehen
Das Feld input_tokens stellt nur die Token dar, die nach dem letzten Cache-Haltepunkt in Ihrer Anfrage kommen - nicht alle Eingabe-Token, die Sie gesendet haben.
Um die Gesamteingabe-Token zu berechnen:
total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokensRäumliche Erklärung:
cache_read_input_tokens = Token vor dem Haltepunkt bereits zwischengespeichert (Lesevorgänge)cache_creation_input_tokens = Token vor dem Haltepunkt, die jetzt zwischengespeichert werden (Schreibvorgänge)input_tokens = Token nach Ihrem letzten Haltepunkt (nicht für Cache berechtigt)Beispiel: Wenn Sie eine Anfrage mit 100.000 Token zwischengespeichertem Inhalt (aus dem Cache gelesen), 0 Token neuer Inhalte, die zwischengespeichert werden, und 50 Token in Ihrer Benutzermeldung (nach dem Cache-Haltepunkt) haben:
cache_read_input_tokens: 100.000Um die Leistung des Prompt-Caching zu optimieren:
Passen Sie Ihre Prompt-Caching-Strategie an Ihr Szenario an:
Wenn Sie unerwartet Verhalten feststellen:
tool_choice und Bildnutzung zwischen Aufrufen konsistent bleibencache_control-Parameter früher im Prompt, um sicherzustellen, dass alle Inhalte zwischengespeichert werden könnentool_use-Inhaltsblöcken stabile Ordnung haben, da einige Sprachen (zum Beispiel Swift, Go) die Schlüsselreihenfolge während der JSON-Konvertierung randomisieren, was Caches brichtÄnderungen an tool_choice oder das Vorhandensein/Fehlen von Bildern überall im Prompt machen den Cache ungültig und erfordern einen neuen Cache-Eintrag. Weitere Details zur Cache-Ungültigkeit finden Sie unter Was den Cache ungültig macht.
Bei Verwendung von Extended Thinking mit Prompt-Caching haben Thinking-Blöcke ein spezielles Verhalten:
Automatisches Caching zusammen mit anderen Inhalten: Während Thinking-Blöcke nicht explizit mit cache_control gekennzeichnet werden können, werden sie als Teil des Anfrageinhalts zwischengespeichert, wenn Sie nachfolgende API-Aufrufe mit Tool-Ergebnissen tätigen. Dies geschieht häufig während der Tool-Nutzung, wenn Sie Thinking-Blöcke zurückgeben, um die Konversation fortzusetzen.
Eingabe-Token-Zählung: Wenn Thinking-Blöcke aus dem Cache gelesen werden, zählen sie als Eingabe-Token in Ihren Nutzungsmetriken. Dies ist wichtig für die Kostenberechnung und Token-Budgetierung.
Cache-Ungültigkeitsmuster:
cache_control-Marker aufWeitere Details zur Cache-Ungültigkeit finden Sie unter Was den Cache ungültig macht.
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]
# Non-tool-result user block causes all thinking blocks to be ignored
# This request is processed as if thinking blocks were never presentWenn ein Nicht-Tool-Ergebnis-Benutzerblock enthalten ist, kennzeichnet er eine neue Assistent-Schleife und alle vorherigen Thinking-Blöcke werden aus dem Kontext entfernt.
Weitere detaillierte Informationen finden Sie in der Extended-Thinking-Dokumentation.
Ab dem 5. Februar 2026 wird Prompt-Caching Workspace-Level-Isolation statt Organization-Level-Isolation verwenden. Caches werden pro Workspace isoliert, um Datentrennung zwischen Workspaces innerhalb derselben Organisation sicherzustellen. Diese Änderung gilt für die Claude API und Azure; Amazon Bedrock und Google Vertex AI behalten Organization-Level-Cache-Isolation bei. Wenn Sie mehrere Workspaces verwenden, überprüfen Sie Ihre Caching-Strategie, um diese Änderung zu berücksichtigen.
Organization Isolation: Caches sind zwischen Organisationen isoliert. Verschiedene Organisationen teilen niemals Caches, auch wenn sie identische Prompts verwenden.
Exakte Übereinstimmung: Cache-Treffer erfordern 100% identische Prompt-Segmente, einschließlich aller Texte und Bilder bis zu und einschließlich des Blocks, der mit Cache-Kontrolle gekennzeichnet ist.
Ausgabe-Token-Generierung: Prompt-Caching hat keine Auswirkung auf die Ausgabe-Token-Generierung. Die Antwort, die Sie erhalten, ist identisch mit dem, was Sie erhalten würden, wenn Prompt-Caching nicht verwendet würde.
Wenn Sie feststellen, dass 5 Minuten zu kurz sind, bietet Anthropic auch eine Cache-Dauer von 1 Stunde gegen zusätzliche Kosten an.
Um den erweiterten Cache zu verwenden, fügen Sie ttl in die cache_control-Definition wie folgt ein:
"cache_control": {
"type": "ephemeral",
"ttl": "5m" | "1h"
}Die Antwort wird detaillierte Cache-Informationen wie die folgende enthalten:
{
"usage": {
"input_tokens": ...,
"cache_read_input_tokens": ...,
"cache_creation_input_tokens": ...,
"output_tokens": ...,
"cache_creation": {
"ephemeral_5m_input_tokens": 456,
"ephemeral_1h_input_tokens": 100,
}
}
}Beachten Sie, dass das aktuelle cache_creation_input_tokens-Feld gleich der Summe der Werte im cache_creation-Objekt ist.
Wenn Sie Prompts haben, die regelmäßig verwendet werden (d. h. System-Prompts, die häufiger als alle 5 Minuten verwendet werden), verwenden Sie weiterhin den 5-Minuten-Cache, da dieser kostenlos aktualisiert wird.
Der 1-Stunden-Cache wird am besten in den folgenden Szenarien verwendet:
Der 5-Minuten- und 1-Stunden-Cache verhalten sich gleich in Bezug auf Latenz. Sie werden generell verbesserte Zeit bis zum ersten Token für lange Dokumente sehen.
Sie können sowohl 1-Stunden- als auch 5-Minuten-Cache-Kontrollen in derselben Anfrage verwenden, aber mit einer wichtigen Einschränkung: Cache-Einträge mit längerer TTL müssen vor kürzeren TTLs erscheinen (d. h. ein 1-Stunden-Cache-Eintrag muss vor allen 5-Minuten-Cache-Einträgen erscheinen).
Beim Mischen von TTLs bestimmen wir drei Abrechnungspositionen in Ihrem Prompt:
A: Die Token-Anzahl beim höchsten Cache-Treffer (oder 0, wenn keine Treffer).B: Die Token-Anzahl beim höchsten 1-Stunden-cache_control-Block nach A (oder gleich A, wenn keine existieren).C: Die Token-Anzahl beim letzten cache_control-Block.Wenn B und/oder C größer als A sind, werden sie notwendigerweise Cache-Fehlschläge sein, weil A der höchste Cache-Treffer ist.
Sie werden belastet für:
A.(B - A).(C - B).Hier sind 3 Beispiele. Dies zeigt die Eingabe-Token von 3 Anfragen, von denen jede unterschiedliche Cache-Treffer und Cache-Fehlschläge hat. Jede hat eine andere berechnete Preisgestaltung, die in den farbigen Feldern angezeigt wird.
Um Ihnen den Einstieg in Prompt Caching zu erleichtern, haben wir ein Prompt-Caching-Kochbuch mit detaillierten Beispielen und Best Practices vorbereitet.
Nachfolgend haben wir mehrere Code-Snippets eingefügt, die verschiedene Prompt-Caching-Muster zeigen. Diese Beispiele demonstrieren, wie Sie Caching in verschiedenen Szenarien implementieren und helfen Ihnen, die praktischen Anwendungen dieser Funktion zu verstehen:
| $3 / MTok |
| $3.75 / MTok |
| $6 / MTok |
| $0.30 / MTok |
| $15 / MTok |
| Claude Sonnet 4.5 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Sonnet 4 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Sonnet 3.7 (deprecated) | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Haiku 4.5 | $1 / MTok | $1.25 / MTok | $2 / MTok | $0.10 / MTok | $5 / MTok |
| Claude Haiku 3.5 | $0.80 / MTok | $1 / MTok | $1.6 / MTok | $0.08 / MTok | $4 / MTok |
| Claude Opus 3 (deprecated) | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Haiku 3 | $0.25 / MTok | $0.30 / MTok | $0.50 / MTok | $0.03 / MTok | $1.25 / MTok |
| Tool-Auswahl | ✓ | ✓ | ✘ | Änderungen am tool_choice-Parameter beeinflussen nur Message-Blöcke |
| Bilder | ✓ | ✓ | ✘ | Das Hinzufügen/Entfernen von Bildern überall im Prompt beeinflußt Message-Blöcke |
| Thinking-Parameter | ✓ | ✓ | ✘ | Änderungen an Extended-Thinking-Einstellungen (Aktivieren/Deaktivieren, Budget) beeinflussen Message-Blöcke |
| Nicht-Tool-Ergebnisse, die an Extended-Thinking-Anfragen übergeben werden | ✓ | ✓ | ✘ | Wenn Nicht-Tool-Ergebnisse in Anfragen übergeben werden, während Extended Thinking aktiviert ist, werden alle zuvor zwischengespeicherten Thinking-Blöcke aus dem Kontext entfernt, und alle Messages im Kontext, die diesen Thinking-Blöcken folgen, werden aus dem Cache entfernt. Weitere Details finden Sie unter Caching mit Thinking-Blöcken. |
cache_creation_input_tokensinput_tokens: 50Dies ist wichtig für das Verständnis sowohl der Kosten als auch der Rate Limits, da input_tokens bei effektiver Nutzung von Caching typischerweise viel kleiner als Ihre Gesamteingabe ist.