Prompt-Caching: Nutzung und Abrechnung

Dokumentation gepflegt von 1ZheAI. Quellen und Korrekturen.

Fehler gefunden? Support kontaktieren mit Seitenadresse und Beschreibung. Senden Sie keine API-Schlüssel oder Kontodaten.

Prompt Caching ermöglicht es, dass das lange Präfix, das Sie wiederholt senden (System-Prompt, Tool-Definitionen, lange Dokumente, Gesprächsverlauf), beim ersten Mal nur als Schreibvorgang abgerechnet wird und danach als Lesevorgang. Auf dieser Seite werden Cache-Lesevorgänge und Cache-Schreibvorgänge zu den offiziellen Listenpreisen abgerechnet, ohne den auf Ein-/Ausgabe angewandten Rabatt. Die Cache-Einheitspreise je Modell sind unter Modelle und Preise aufgeführt.

Fazit zuerst

• Claude Code hat Caching standardmäßig aktiviert; es wirkt, sobald Sie sich verbinden.
• Beim Aufruf aus eigenem Code fügen Sie cache_control zum Inhaltsblock hinzu, den Sie cachen möchten, und verwenden dabei das native /v1/messages. Die OpenAI-kompatible Schnittstelle cacht derzeit nicht.
• Um festzustellen, ob ein Treffer stattgefunden hat, prüfen Sie ausschließlich, ob usage.cache_read_input_tokens der Antwort größer als 0 ist.
• Der Cache lebt standardmäßig 5 Minuten, und jeder Treffer setzt den Timer zurück. Sie können auch "ttl": "1h" verwenden, um einen 1-Stunden-Cache zu schreiben, zu einem höheren Schreibpreis.

So aktivieren Sie es

Fügen Sie "cache_control": {"type": "ephemeral"} zu einem Inhaltsblock in system, tools oder messages hinzu; dieser Block und alles, was davor steht, wird gecacht. Eine einzelne Anfrage kann höchstens 4 Cache-Breakpoints haben.

bash

curl https://1zheai.com/v1/messages \
  -H "x-api-key: $ONEZHE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 256,
    "system": [
      {
        "type": "text",
        "text": "这里放一段很长、每次都一样的内容：项目说明、代码规范、参考文档……",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [{"role": "user", "content": "根据上面的规范，审查这段代码：..."}]
  }'

Ist das zu cachende Präfix zu kurz, wird die Anfrage normal verarbeitet, aber einfach nicht gecacht, und es wird kein Fehler ausgelöst. Die Mindestlänge variiert je nach Modell; siehe die Tabelle unten.

Minimale cachierbare Länge

Das Folgende stammt aus Anthropics offizieller Dokumentation (2026-10-14):

Minimale Token-Anzahl	Modelle
512	Fable 5.1, Fable 5, Opus 5.5, Opus 5, Sonnet 5.5, Haiku 5.5
1.024	Opus 4.8, Sonnet 5, Sonnet 4.6, Sonnet 4.5
2.048	Opus 4.7
4.096	Opus 4.6, Opus 4.5, Haiku 4.5

Treffer bestätigen

Senden Sie dieselbe Anfrage zweimal (nicht mehr als 5 Minuten auseinander) und vergleichen Sie das usage beider. Nachfolgend die tatsächlichen Ergebnisse, gemessen am 2026-10-15 mit claude-sonnet-5-5, mit etwa 18.000 Tokens festem Text im System:

第一次：写入缓存

第一次：写入缓存

{
  "input_tokens": 23,
  "cache_creation_input_tokens": 17920,
  "cache_read_input_tokens": 0,
  "cache_creation": {"ephemeral_5m_input_tokens": 17920, "ephemeral_1h_input_tokens": 0},
  "output_tokens": 4
}

第二次：命中缓存

第二次：命中缓存

{
  "input_tokens": 23,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 17920,
  "cache_creation": {"ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 0},
  "output_tokens": 4
}

Ist das zweite cache_read_input_tokens größer als 0, wird der Cache gelesen. Die Cache-Schreib- und Cache-Lese-Tokens jedes Aufrufs erscheinen auch in der Spalte Token des Aufrufprotokolls, wobei Lesevorgänge als „cache↓“ und Schreibvorgänge als „↑“ erfasst werden.

So wird abgerechnet

Typ	Offizieller Einheitspreis	1折AI-Einheitspreis
Cache-Schreiben (5 Minuten)	Eingabepreis × 1,25	Offizieller Listenpreis, kein Rabatt
Cache-Schreiben (1 Stunde)	Eingabepreis × 2	Offizieller Listenpreis, kein Rabatt
Cache-Lesen	Eingabepreis × 0,1 (0,05 für Opus 5.5 und Sonnet 5.5, 0,025 für Fable 5.1)	Offizieller Listenpreis, kein Rabatt

Der offizielle Preis für einen 5-Minuten-Cache-Schreibvorgang beträgt in der Regel das 1,25-Fache des offiziellen Eingabepreises. Auf dieser Seite hat die Eingabe einen Rabatt, das Caching aber nicht; daher können Sie nicht aus dem offiziellen Multiplikator schließen, dass sich ein einzelner Cache-Lesevorgang amortisiert; Sie müssen den Modellrabatt, die Schreibkosten und die Anzahl der wiederholten Lesevorgänge vergleichen. Vollständige durchgerechnete Beispiele finden Sie unter Preise und Abrechnung.

1-Stunden-Cache

Fügen Sie "ttl": "1h" zu cache_control hinzu, und der Cache wird 1 Stunde lang aufbewahrt — geeignet für Präfixe mit Intervallen über 5 Minuten, die weiterhin wiederholt verwendet werden:

json

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

Schreibvorgänge werden mit dem 2-Fachen des offiziellen Eingabepreises abgerechnet, nicht mit dem rabattierten Eingabepreis; Lesevorgänge verhalten sich wie beim 5-Minuten-Cache. Die geschriebenen Tokens erscheinen in cache_creation.ephemeral_1h_input_tokens der Antwort. Ob Sie den 1-Stunden-Cache wählen, sollten Sie anhand des Intervalls zwischen den beiden Anfragen, der Schreibkosten und der Anzahl der wiederholten Lesevorgänge beurteilen.

Caching in Claude Code

Claude Code platziert automatisch Cache-Breakpoints auf dem System-Prompt, den Tool-Definitionen und dem Gesprächsverlauf; die offizielle Erläuterung finden Sie hier. Damit es besser trifft:

• Arbeiten Sie kontinuierlich in einer Sitzung weiter; halten Sie nicht lange in der Mitte an. Der Cache läuft ab, wenn er 5 Minuten ungenutzt bleibt.
• Nachfolgende Anfragen in derselben Sitzung lesen den Cache. Gemessen am 2026-10-15 las die zweite Runde bei einer zweirundigen Claude-Code-Aufgabe 31.440 Cache-Tokens und schrieb 115 Tokens. Beim Start einer neuen Sitzung muss die erste Runde möglicherweise das gesamte Präfix neu schreiben (gemessen bei etwa 30.000 Tokens), und dieser Aufruf wird teurer als die späteren.
• Vermeiden Sie es, CLAUDE.md zu ändern, MCP-Server zu wechseln oder mitten in der Sitzung das Modell zu ändern; all das verändert das Präfix.
• Setzen Sie DISABLE_PROMPT_CACHING=1 nicht; diese Umgebungsvariable schaltet das Caching für alle Modelle ab.

Kann die OpenAI-kompatible Schnittstelle Caching verwenden?

Derzeit nicht. Gemessen am 2026-10-15 mit etwa 3.100 Tokens festem Text in der System-Nachricht von /v1/chat/completions, zweimal hintereinander gesendet, war unabhängig davon, ob cache_control zum Inhaltsblock hinzugefügt wurde, das usage beider Antworten:

json

{"prompt_tokens": 3167, "completion_tokens": 4, "total_tokens": 3171}

Es gibt kein prompt_tokens_details.cached_tokens, und die Cache-Lese- und Cache-Schreibvorgänge im Aufrufprotokoll sind beide 0; die gesamte Anfrage wird zum Eingabepreis abgerechnet. Für Szenarien, die Caching benötigen, verwenden Sie bitte /v1/messages (Anthropic-SDK oder Claude Code).

FAQ

Warum gibt es immer nur cache_creation, aber kein cache_read?

Der Cache wurde geschrieben, aber die nächste Anfrage hat ihn nicht gelesen. Fehlersuche der Reihe nach: Waren die beiden Anfragen mehr als 5 Minuten auseinander? Ist der Inhalt vor dem Breakpoint byte-identisch (Zeitstempel und Zufalls-IDs im System machen ihn jedes Mal anders)? Wurde das Modell gewechselt? Hat das Präfix die obige Mindestlänge erreicht?

Kann ich die Cache-Trefferquote sehen?

Die Cache-Lese- und Cache-Schreib-Tokens jedes Aufrufs stehen im Aufrufprotokoll, sodass Sie selbst nachrechnen können: Cache-Lesevorgänge ÷ (Eingabe + Cache-Schreibvorgänge + Cache-Lesevorgänge).