Leitfaden zum Claude-Kontext-Caching

Claude Context Cache eignet sich für die Wiederverwendung langer Präfixe wie System-Prompts, Dokumente, Codebasen oder Gesprächsverläufe. Nachdem Sie einem stabilen Präfix cache_control hinzugefügt haben, erstellt die erste Anfrage einen Cache und nachfolgende Anfragen können den noch gültigen Cache lesen. Legen Sie zunächst Ihren API-Schlüssel fest:

export API_KEY="IHR_API_SCHLUESSEL"

Die Beispiele in diesem Leitfaden verwenden claude-sonnet-5. Ob andere Modelle Context Cache unterstützen, erfahren Sie in der Modelldokumentation der Plattform.

Anwendungsfälle

Wenn mehrere Anfragen wiederholt dieselben umfangreichen Inhalte enthalten, können Sie einen stabilen Präfix zwischenspeichern, zum Beispiel:

Einen langen System-Prompt
Eine feste Wissensdatenbank oder Produktdokumentation
Einen unveränderten Gesprächsverlauf aus mehreren Dialogrunden
Wiederverwendete Codebasen, Tool-Definitionen und Anweisungen

Context Cache eignet sich für Anfragen, bei denen der Inhalt am Anfang unverändert bleibt, während sich die abschließende Frage fortlaufend ändert.

Claude Messages API

5-Minuten-Cache

Fügen Sie cache_control zu dem Inhaltsblock hinzu, der zwischengespeichert werden soll:

curl "https://api.apimart.ai/v1/messages" \
  -H "x-api-key: $API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "Fügen Sie hier den langen Präfix ein, der wiederverwendet werden soll...",
        "cache_control": {
          "type": "ephemeral"
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Beantworten Sie die Frage anhand des obigen Inhalts."
      }
    ]
  }'

system muss als Array von Inhaltsblöcken angegeben werden. Bei einem system-String kann cache_control nicht hinzugefügt werden.

Wenn ttl weggelassen wird, beträgt die Cache-Gültigkeitsdauer standardmäßig 5 Minuten.

1-Stunden-Cache

Für einen 1-Stunden-Cache müssen Sie zusätzlich den Anfrage-Header anthropic-beta senden und ttl auf 1h setzen:

curl "https://api.apimart.ai/v1/messages" \
  -H "x-api-key: $API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: extended-cache-ttl-2025-04-11" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "Fügen Sie hier den langen Präfix ein, der wiederverwendet werden soll...",
        "cache_control": {
          "type": "ephemeral",
          "ttl": "1h"
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Beantworten Sie die Frage anhand des obigen Inhalts."
      }
    ]
  }'

Unterstützte TTL-Werte:

TTL	Bedeutung
`5m`	5 Minuten zwischenspeichern; wird verwendet, wenn `ttl` weggelassen wird
`1h`	1 Stunde zwischenspeichern; der entsprechende `anthropic-beta`-Header muss ebenfalls gesendet werden

Felder zur Nutzung in der Antwort

Die Claude Messages API gibt gewöhnliche Eingabe-, Cache-Schreib- und Cache-Lese-Token getrennt im Objekt usage zurück:

{
  "usage": {
    "input_tokens": 23,
    "cache_creation_input_tokens": 2619,
    "cache_read_input_tokens": 0,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 2619,
      "ephemeral_1h_input_tokens": 0
    },
    "output_tokens": 24
  }
}

Die Gesamtzahl der Eingabe-Token wird wie folgt berechnet:

input_tokens
+ cache_creation_input_tokens
+ cache_read_input_tokens

Diese drei Werte überschneiden sich nicht. Bei der ersten Anfrage ist in der Regel cache_creation_input_tokens > 0; wenn Sie denselben stabilen Präfix erneut senden, sollte cache_read_input_tokens > 0 sein.

OpenAI-kompatible API

Anfragebeispiel

Bei der Verwendung des Caches über /v1/chat/completions wird cache_control ähnlich wie bei der Claude Messages API angegeben:

curl "https://api.apimart.ai/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "system",
        "content": [
          {
            "type": "text",
            "text": "Fügen Sie hier den langen Präfix ein, der wiederverwendet werden soll...",
            "cache_control": {
              "type": "ephemeral"
            }
          }
        ]
      },
      {
        "role": "user",
        "content": "Beantworten Sie die Frage anhand des obigen Inhalts."
      }
    ]
  }'

1-Stunden-Cache

Das OpenAI-kompatible Format unterstützt ebenfalls einen 1-Stunden-Cache. Fügen Sie einfach den Anfrage-Header anthropic-beta hinzu und setzen Sie in cache_control den Wert ttl: "1h":

-H "anthropic-beta: extended-cache-ttl-2025-04-11"

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

`content` muss ein Array sein

Im OpenAI-kompatiblen Format muss cache_control innerhalb eines konkreten Inhaltsblocks stehen. Es kann nicht an eine Nachricht mit String-Inhalt angehängt werden.

{
  "role": "system",
  "content": "Fügen Sie hier den langen Präfix ein...",
  "cache_control": {
    "type": "ephemeral"
  }
}

Die obige Schreibweise aktiviert den Cache nicht, führt aber auch nicht zu einem Anfragefehler. Die korrekte Schreibweise lautet:

{
  "role": "system",
  "content": [
    {
      "type": "text",
      "text": "Fügen Sie hier den langen Präfix ein...",
      "cache_control": {
        "type": "ephemeral"
      }
    }
  ]
}

Wenn content als String angegeben wird, wird die Cache-Markierung ignoriert und der Eingabeinhalt weiterhin als gewöhnliche Eingabe verarbeitet. Prüfen Sie anhand der Cache-Nutzungsfelder in der Antwort, ob der Cache getroffen wurde.

`user`- oder `assistant`-Inhaltsblöcke zwischenspeichern

Sie können cache_control auch in einem Inhaltsblock einer user- oder assistant-Nachricht platzieren, um lange Dokumente oder einen Präfix aus mehreren Dialogrunden zwischenzuspeichern:

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "Fügen Sie hier das lange Dokument ein, das wiederverwendet werden soll...",
      "cache_control": {
        "type": "ephemeral"
      }
    },
    {
      "type": "text",
      "text": "Fassen Sie die drei wichtigsten Punkte des obigen Dokuments zusammen."
    }
  ]
}

Teilen Sie den stabilen Inhalt und die aktuelle Frage in unterschiedliche Inhaltsblöcke auf und fügen Sie cache_control nur dem stabilen Inhaltsblock hinzu.

Felder zur Nutzung in der Antwort

Das OpenAI-kompatible Format meldet die Cache-Nutzung über andere Felder:

{
  "usage": {
    "prompt_tokens": 1942,
    "completion_tokens": 22,
    "prompt_tokens_details": {
      "cached_tokens": 1921,
      "cache_write_tokens": 0
    },
    "claude_cache_creation_5_m_tokens": 0,
    "claude_cache_creation_1_h_tokens": 0
  }
}

Feldzuordnung:

Bedeutung	Claude Messages API	OpenAI-kompatible API
Gesamteingabe	Summe der drei Eingabefelder	`prompt_tokens`
Cache-Lesevorgang	`cache_read_input_tokens`	`prompt_tokens_details.cached_tokens`
Allgemeines Feld für Cache-Schreibvorgänge	`cache_creation_input_tokens`	`prompt_tokens_details.cache_write_tokens` (nur belegt, wenn keine TTL-Aufschlüsselung vorhanden ist)
Schreibvorgang in den 5-Minuten-Cache	`cache_creation.ephemeral_5m_input_tokens`	`claude_cache_creation_5_m_tokens`
Schreibvorgang in den 1-Stunden-Cache	`cache_creation.ephemeral_1h_input_tokens`	`claude_cache_creation_1_h_tokens`
Ausgabe	`output_tokens`	`completion_tokens`

Wenn prompt_tokens_details.cache_write_tokens den Wert 0 hat, prüfen Sie trotzdem claude_cache_creation_5_m_tokens und claude_cache_creation_1_h_tokens. Wenn Felder mit TTL-Aufschlüsselung vorhanden sind, wird die Cache-Schreibmenge über das entsprechende Feld zurückgegeben.

In claude_cache_creation_5_m_tokens und claude_cache_creation_1_h_tokens stehen Unterstriche zwischen der Zahl und der Einheit. Verwenden Sie die Feldnamen genau so, wie sie in der Antwort zurückgegeben werden.

Die OpenAI-kompatible API kann auch dann eine SSE-Streaming-Antwort zurückgeben, wenn Sie stream: true nicht ausdrücklich übergeben. Der Client sollte chat.completion.chunk verarbeiten können. Die Nutzung steht im letzten Datenblock, der usage enthält.

Bedingungen für einen Cache-Treffer

Der Präfix erreicht die Mindestlänge

Der Cache-Präfix des Beispielmodells muss in der Regel mindestens etwa 1024 Token umfassen. Bei einem kürzeren Präfix kann die Cache-Markierung ohne Fehlermeldung ignoriert werden.

Der Präfix bleibt bytegenau identisch

Text, Leerzeichen, Zeilenumbrüche und die Reihenfolge der Inhaltsblöcke im Cache-Präfix müssen unverändert bleiben. Fügen Sie dem stabilen Präfix keine dynamischen Inhalte wie Zeitstempel, zufällige IDs oder Anfragezähler hinzu.

Die Anfrage hat keine Modellablehnung ausgelöst

Wenn die Anfrage eine Modellablehnung auslöst, kann die Antwort dennoch Cache-Erstellungs-Token melden, der Cache wird bei der nächsten Anfrage jedoch nicht gelesen. Prüfen Sie bei der Fehlersuche nach ausbleibenden Cache-Treffern auch, ob stop_reason den Wert refusal hat.

Der Cache ist noch gültig

Die Cache-Gültigkeitsdauer beträgt 5 Minuten oder 1 Stunde und wird ab dem letzten Zugriff berechnet. Ein Cache-Treffer erneuert die Gültigkeitsdauer.

Abrechnungsnutzung

Die Cache-bezogene Nutzung wird in drei Kategorien unterteilt:

Nutzung	Zeitpunkt
Cache-Schreibvorgang	Bei der ersten Cache-Erstellung
Cache-Lesevorgang	Wenn eine nachfolgende Anfrage den Cache trifft
Gewöhnliche Eingabe	Eingabe außerhalb des Cache-Präfixes

Die drei Nutzungskategorien überschneiden sich nicht. Cache-Schreibvorgänge kosten in der Regel mehr als gewöhnliche Eingaben, während Cache-Lesevorgänge in der Regel weniger kosten. Context Cache eignet sich daher besonders für stabile Präfixe, die innerhalb der TTL wiederverwendet werden.

Minimales reproduzierbares Beispiel

Das folgende Skript erzeugt zunächst einen ausreichend langen stabilen Präfix und sendet anschließend dieselbe Anfrage zweimal. In der zweiten Antwort sollte cache_read_input_tokens > 0 erscheinen.

python3 - <<'PY' > /tmp/claude-cache-request.json
import json

paragraph = (
    "Prompt caching stores a prefix of the request so that later requests "
    "can reuse the same byte-identical prefix without processing it again. "
)

system_text = (
    "You are a documentation assistant. Reference material follows.\n\n"
    + paragraph * 40
)

print(json.dumps({
    "model": "claude-sonnet-5",
    "max_tokens": 32,
    "system": [{
        "type": "text",
        "text": system_text,
        "cache_control": {"type": "ephemeral"}
    }],
    "messages": [{
        "role": "user",
        "content": "In one sentence, what must remain unchanged?"
    }]
}))
PY

for request_number in 1 2; do
  echo "Anfrage ${request_number}"
  curl -s "https://api.apimart.ai/v1/messages" \
    -H "x-api-key: $API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "Content-Type: application/json" \
    --data @/tmp/claude-cache-request.json \
  | python3 -c "import json, sys; print(json.load(sys.stdin)['usage'])"
done

Erwartetes Ergebnis:

Anfrage 1: cache_creation_input_tokens > 0, cache_read_input_tokens = 0
Anfrage 2: cache_creation_input_tokens = 0, cache_read_input_tokens > 0

Checkliste zur Fehlerbehebung

Wenn der Cache nicht getroffen wird, prüfen Sie die folgenden Punkte in dieser Reihenfolge:

Hat stop_reason den Wert refusal?
Erreicht der Cache-Präfix die für das Modell erforderliche Mindestanzahl an Token?
Sind die stabilen Präfixe der beiden Anfragen bytegenau identisch?
Ist content im OpenAI-kompatiblen Format ein Array?
Befindet sich cache_control in einem konkreten Inhaltsblock?
Sind für einen 1-Stunden-Cache sowohl ttl: "1h" als auch der entsprechende anthropic-beta-Header festgelegt?
Ist die TTL des Caches bereits abgelaufen?
Lesen Sie die Cache-Nutzungsfelder der verwendeten API aus?

Übersicht

Textserie

Bildserie

Videoserie

Audioserie

Moderationsserie

Upload-Verwaltung

Aufgabenverwaltung

Kontoverwaltung

Leitfaden zum Claude-Kontext-Caching

Anwendungsfälle

Claude Messages API

5-Minuten-Cache

1-Stunden-Cache

Felder zur Nutzung in der Antwort

OpenAI-kompatible API

Anfragebeispiel

1-Stunden-Cache

`content` muss ein Array sein

`user`- oder `assistant`-Inhaltsblöcke zwischenspeichern

Felder zur Nutzung in der Antwort

Bedingungen für einen Cache-Treffer

Der Präfix erreicht die Mindestlänge

Der Präfix bleibt bytegenau identisch

Die Anfrage hat keine Modellablehnung ausgelöst

Der Cache ist noch gültig

Abrechnungsnutzung

Minimales reproduzierbares Beispiel

Checkliste zur Fehlerbehebung

​Anwendungsfälle

​Claude Messages API

​5-Minuten-Cache

​1-Stunden-Cache

​Felder zur Nutzung in der Antwort

​OpenAI-kompatible API

​Anfragebeispiel

​1-Stunden-Cache

​content muss ein Array sein

​user- oder assistant-Inhaltsblöcke zwischenspeichern

​Felder zur Nutzung in der Antwort

​Bedingungen für einen Cache-Treffer

​Der Präfix erreicht die Mindestlänge

​Der Präfix bleibt bytegenau identisch

​Die Anfrage hat keine Modellablehnung ausgelöst

​Der Cache ist noch gültig

​Abrechnungsnutzung

​Minimales reproduzierbares Beispiel

​Checkliste zur Fehlerbehebung

Anwendungsfälle

Claude Messages API

5-Minuten-Cache

1-Stunden-Cache

Felder zur Nutzung in der Antwort

OpenAI-kompatible API

Anfragebeispiel

1-Stunden-Cache

`content` muss ein Array sein

`user`- oder `assistant`-Inhaltsblöcke zwischenspeichern

Felder zur Nutzung in der Antwort

Bedingungen für einen Cache-Treffer

Der Präfix erreicht die Mindestlänge

Der Präfix bleibt bytegenau identisch

Die Anfrage hat keine Modellablehnung ausgelöst

Der Cache ist noch gültig

Abrechnungsnutzung

Minimales reproduzierbares Beispiel

Checkliste zur Fehlerbehebung