Prompt-Caching

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-sonnet-4-5",
    "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}

​

Wie Prompt-Caching funktioniert

1. Das System prüft, ob ein Prompt-Präfix bis zu einem angegebenen Cache-Haltepunkt bereits aus einer kürzlichen Abfrage zwischengespeichert ist.
2. Falls gefunden, wird die zwischengespeicherte Version verwendet, was die Verarbeitungszeit und Kosten reduziert.
3. Andernfalls wird der vollständige Prompt verarbeitet und das Präfix zwischengespeichert, sobald die Antwort beginnt.

• Prompts mit vielen Beispielen
• Große Mengen an Kontext oder Hintergrundinformationen
• Sich wiederholende Aufgaben mit konsistenten Anweisungen
• Lange Multi-Turn-Gespräche

​

Preisgestaltung

​

Wie man Prompt-Caching implementiert

​

Unterstützte Modelle

• Claude Opus 4.1
• Claude Opus 4
• Claude Sonnet 4.5
• Claude Sonnet 4
• Claude Sonnet 3.7
• Claude Haiku 4.5
• Claude Haiku 3.5
• Claude Haiku 3
• Claude Opus 3 (veraltet)

​

Strukturierung Ihres Prompts

​

Wie die automatische Präfix-Überprüfung funktioniert

• Wenn Sie einen cache_control-Haltepunkt hinzufügen, prüft das System automatisch auf Cache-Treffer an allen vorherigen Inhaltsblock-Grenzen (bis zu etwa 20 Blöcke vor Ihrem expliziten Haltepunkt)
• Wenn eine dieser vorherigen Positionen mit zwischengespeichertem Inhalt aus früheren Anfragen übereinstimmt, verwendet das System das längste übereinstimmende Präfix
• Dies bedeutet, dass Sie nicht mehrere Haltepunkte benötigen, um Caching zu aktivieren - einer am Ende ist ausreichend

​

Wann mehrere Haltepunkte verwendet werden sollten

• Verschiedene Abschnitte zwischenspeichern, die sich mit unterschiedlichen Häufigkeiten ändern (z. B. Tools ändern sich selten, aber der Kontext wird täglich aktualisiert)
• Mehr Kontrolle darüber haben, was genau zwischengespeichert wird
• Caching für Inhalte sicherstellen, die mehr als 20 Blöcke vor Ihrem endgültigen Haltepunkt liegen

​

Cache-Einschränkungen

• 1024 Token für Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4.5, Claude Sonnet 4, Claude Sonnet 3.7 (veraltet) und Claude Opus 3 (veraltet)
• 4096 Token für Claude Haiku 4.5
• 2048 Token für Claude Haiku 3.5 und Claude Haiku 3

​

Verständnis der Cache-Haltepunkt-Kosten

• Cache-Schreibvorgänge: Wenn neuer Inhalt in den Cache geschrieben wird (25% mehr als Basis-Eingabe-Token für 5-Minuten-TTL)
• Cache-Lesevorgänge: Wenn zwischengespeicherter Inhalt verwendet wird (10% des Basis-Eingabe-Token-Preises)
• Reguläre Eingabe-Token: Für jeden nicht zwischengespeicherten Inhalt

​

Was zwischengespeichert werden kann

• Tools: Tool-Definitionen im tools-Array
• Systemmeldungen: Inhaltsblöcke im system-Array
• Textmeldungen: Inhaltsblöcke im messages.content-Array, sowohl für Benutzer- als auch für Assistent-Turns
• Bilder & Dokumente: Inhaltsblöcke im messages.content-Array, in Benutzer-Turns
• Tool-Nutzung und Tool-Ergebnisse: Inhaltsblöcke im messages.content-Array, sowohl in Benutzer- als auch in Assistent-Turns

​

Was nicht zwischengespeichert werden kann

• 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 citations) können nicht direkt zwischengespeichert werden. Speichern Sie stattdessen den Top-Level-Block zwischen. Im Fall von Zitaten können die Top-Level-Dokument-Inhaltsblöcke, die als Quellenmaterial für Zitate dienen, zwischengespeichert werden. Dies ermöglicht es Ihnen, Prompt-Caching effektiv mit Zitaten zu verwenden, indem Sie die Dokumente zwischenspeichern, auf die Zitate verweisen werden.
• Leere Textblöcke können nicht zwischengespeichert werden.

​

Was den Cache ungültig macht

​

Verfolgung der Cache-Leistung

• 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.

​

Best Practices für effektives Caching

• Speichern Sie stabilen, wiederverwendbaren Inhalt wie Systemanweisungen, Hintergrundinformationen, große Kontexte oder häufige Tool-Definitionen zwischen.
• Platzieren Sie zwischengespeicherten Inhalt am Anfang des Prompts für beste Leistung.
• Verwenden Sie Cache-Haltepunkte strategisch, um verschiedene zwischenspeicherbare Präfix-Abschnitte zu trennen.
• Analysieren Sie regelmäßig Cache-Hit-Raten und passen Sie Ihre Strategie nach Bedarf an.

​

Optimierung für verschiedene Anwendungsfälle

• Conversational Agents: Reduzieren Sie Kosten und Latenz für erweiterte Gespräche, besonders solche mit langen Anweisungen oder hochgeladenen Dokumenten.
• Coding Assistants: Verbessern Sie Autocomplete und Codebase-Q&A, indem Sie relevante Abschnitte oder eine zusammengefasste Version der Codebase im Prompt behalten.
• Große Dokumentenverarbeitung: Integrieren Sie vollständiges Langform-Material einschließlich Bilder in Ihren Prompt, ohne die Antwortlatenz zu erhöhen.
• Detaillierte Anweisungssätze: Teilen Sie umfangreiche Listen von Anweisungen, Verfahren und Beispielen, um Claudes Antworten zu verfeinern. Entwickler fügen normalerweise ein oder zwei Beispiele in den Prompt ein, aber mit Prompt-Caching können Sie noch bessere Leistung erzielen, indem Sie 20+ diverse Beispiele von hochwertigen Antworten einbeziehen.
• Agentic Tool Use: Verbessern Sie die Leistung für Szenarien mit mehreren Tool-Aufrufen und iterativen Code-Änderungen, bei denen jeder Schritt normalerweise einen neuen API-Aufruf erfordert.
• Sprechen Sie mit Büchern, Papieren, Dokumentation, Podcast-Transkripten und anderen Langform-Inhalten: Bringen Sie jede Wissensbasis zum Leben, indem Sie das gesamte Dokument(e) in den Prompt einbetten und Benutzer es befragen lassen.

​

Fehlerbehebung bei häufigen Problemen

• Stellen Sie sicher, dass zwischengespeicherte Abschnitte identisch sind und mit cache_control an den gleichen Stellen über Aufrufe hinweg gekennzeichnet sind
• Überprüfen Sie, dass Aufrufe innerhalb der Cache-Lebensdauer (standardmäßig 5 Minuten) erfolgen
• Überprüfen Sie, dass tool_choice und die Bildnutzung zwischen Aufrufen konsistent bleiben
• Validieren Sie, dass Sie mindestens die Mindestanzahl von Token zwischenspeichern
• Das System prüft automatisch auf Cache-Treffer an vorherigen Inhaltsblock-Grenzen (bis zu ~20 Blöcke vor Ihrem Haltepunkt). Für Prompts mit mehr als 20 Inhaltsblöcken benötigen Sie möglicherweise zusätzliche cache_control-Parameter früher im Prompt, um sicherzustellen, dass alle Inhalte zwischengespeichert werden können
• Überprüfen Sie, dass die Schlüssel in Ihren tool_use-Inhaltsblöcken stabile Ordnung haben, da einige Sprachen (z. B. Swift, Go) die Schlüsselreihenfolge während der JSON-Konvertierung randomisieren und Caches unterbrechen

​

Caching mit Thinking-Blöcken

• Der Cache bleibt gültig, wenn nur Tool-Ergebnisse als Benutzermeldungen bereitgestellt werden
• Der Cache wird ungültig gemacht, wenn Nicht-Tool-Ergebnis-Benutzerinhalte hinzugefügt werden, was dazu führt, dass alle vorherigen Thinking-Blöcke entfernt werden
• Dieses Caching-Verhalten tritt auch ohne explizite cache_control-Markierungen auf

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 present

​

Cache-Speicherung und Freigabe

• Organisationsisolation: Caches sind zwischen Organisationen isoliert. Verschiedene Organisationen teilen niemals Caches, auch wenn sie identische Prompts verwenden.
• Genaue Ü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.

​

1-Stunden-Cache-Dauer

"cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
}

{
    "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,
        }
    }
}

​

Wann der 1-Stunden-Cache verwendet werden sollte

• Wenn Sie Prompts haben, die wahrscheinlich weniger häufig als alle 5 Minuten, aber häufiger als jede Stunde verwendet werden. Zum Beispiel, wenn ein Agentic-Side-Agent länger als 5 Minuten dauert, oder wenn Sie ein langes Chat-Gespräch mit einem Benutzer speichern und Sie im Allgemeinen erwarten, dass dieser Benutzer möglicherweise nicht in den nächsten 5 Minuten antwortet.
• Wenn Latenz wichtig ist und Ihre nachfolgenden Prompts möglicherweise über 5 Minuten hinaus gesendet werden.
• Wenn Sie Ihre Rate-Limit-Auslastung verbessern möchten, da Cache-Treffer nicht gegen Ihr Rate-Limit abgezogen werden.

​

Mischen verschiedener TTLs

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

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

​

Prompt-Caching-Beispiele

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing legal documents."
        },
        {
            "type": "text",
            "text": "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What are the key terms and conditions in this agreement?"
        }
    ]
}'

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature, either celsius or fahrenheit"
                    }
                },
                "required": ["location"]
            }
        },
        # many more tools
        {
            "name": "get_time",
            "description": "Get the current time in a given time zone",
            "input_schema": {
                "type": "object",
                "properties": {
                    "timezone": {
                        "type": "string",
                        "description": "The IANA time zone name, e.g. America/Los_Angeles"
                    }
                },
                "required": ["timezone"]
            },
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What is the weather and time in New York?"
        }
    ]
}'

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "...long system prompt",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Hello, can you tell me more about the solar system?",
                }
            ]
        },
        {
            "role": "assistant",
            "content": "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you would like to know more about?"
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Good to know."
                },
                {
                    "type": "text",
                    "text": "Tell me more about Mars.",
                    "cache_control": {"type": "ephemeral"}
                }
            ]
        }
    ]
}'

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "search_documents",
            "description": "Search through the knowledge base",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Search query"
                    }
                },
                "required": ["query"]
            }
        },
        {
            "name": "get_document",
            "description": "Retrieve a specific document by ID",
            "input_schema": {
                "type": "object",
                "properties": {
                    "doc_id": {
                        "type": "string",
                        "description": "Document ID"
                    }
                },
                "required": ["doc_id"]
            },
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "system": [
        {
            "type": "text",
            "text": "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",
            "cache_control": {"type": "ephemeral"}
        },
        {
            "type": "text",
            "text": "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "Can you search for information about Mars rovers?"
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "tool_use",
                    "id": "tool_1",
                    "name": "search_documents",
                    "input": {"query": "Mars rovers"}
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "tool_1",
                    "content": "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document."
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Yes, please tell me about the Perseverance rover specifically.",
                    "cache_control": {"type": "ephemeral"}
                }
            ]
        }
    ]
}'

​

Häufig gestellte Fragen

python client.beta.prompt_caching.messages.create(...)

python client.messages.create(...)

client.beta.promptCaching.messages.create(...)

client.messages.create(...)