Claude-Prompt-Caching – Tarife, das Nutzungsobjekt und warum Trefferquoten hinter einem Gateway sinken

Prompt-Caching ist der größte einzelne Hebel für die Kosten eines Agents und zugleich derjenige, der am ehesten unbemerkt nicht funktioniert. Korrekt markiert wird der wiederholte Teil Ihrer Anfrage mit einem Zehntel des Eingabepreises abgerechnet. Falsch markiert — oder über etwas weitergeleitet, das Ihr Präfix umschreibt — wird er teurer als zum normalen Tarif abgerechnet, weil Sie für das Schreiben von Cache-Einträgen bezahlen, die niemand liest.

Der Mechanismus ist an anderer Stelle gut dokumentiert. Nicht dokumentiert ist jedoch, was sich ändert, wenn die Anfrage über ein Gateway läuft — und genau das ist die Situation der meisten Leserinnen und Leser. Beides folgt unten.

Der Mechanismus kurz erklärt

Sie markieren ein stabiles Präfix — einen System-Prompt, ein Tool-Schema oder ein Dokument — und der Anbieter speichert dessen verarbeitete Form. Die nächste Anfrage, deren Präfix exakt übereinstimmt, liest es aus, statt es erneut zu verarbeiten.

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "<your long, stable instructions>",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "..." }]
}

Zwei Eigenschaften leisten die gesamte Arbeit und verursachen alle Probleme. Der Abgleich erfolgt mit einem Präfix, sodass alles, was sich am Anfang ändert, alles danach ungültig macht. Außerdem hat ein Eintrag eine Lebensdauer, sodass eine Unterhaltung mit langen Pausen zwischen den Runden neu erstellt statt gelesen wird.

Was es kostet

Die dritte Spalte zeigt das Standardverhältnis: Ein Lesevorgang kostet ein Zehntel der Eingabe. Auch die vierte Spalte ist standardisiert — ein Cache-Schreibvorgang kostet 1,25× der Eingabe, den von Anthropic angegebenen Multiplikator für einen Eintrag von fünf Minuten. Da beide Verhältnisse auf Kunavos Eingabepreis angewendet werden, haben beide gegenüber der Anthropic-Preisliste denselben Rabatt wie die Eingabe des Modells. Kunavo weicht bei dem Eintrag von einer Stunde von Anthropic ab: Anthropic gibt für diesen Schreibvorgang 2× der Eingabe an, Kunavo berechnet dafür ebenfalls 1,25×. Das ist besonders für Workloads relevant, die häufig neu aufbauen — langlebige Agents, langsame Unterhaltungen und alles, dessen Präfix sich häufig ändert —, weil bei diesen Workloads Schreibvorgänge und nicht Lesevorgänge die Cache-Zeile der Rechnung dominieren.

Beide Werte werden zur Renderzeit aus dem Katalog gelesen, aus derselben Quelle, aus der auch die Preistabelle und der Claude-Rechner lesen — auf dieser Seite gibt es keine manuell eingetragenen Tarife.

Das Nutzungsobjekt lesen

Leiten Sie das Cache-Verhalten nicht aus der Rechnung ab; jede Antwort teilt es Ihnen direkt mit, und die drei Token-Zählungen liefern die vollständige Diagnose.

// The four numbers that tell you whether caching is working.
// Read them from every response before you tune anything.
"usage": {
  "input_tokens": 312,                     // billed at the input rate
  "cache_creation_input_tokens": 0,        // billed at the write rate
  "cache_read_input_tokens": 24106,        // billed at the read rate
  "output_tokens": 890
}

// A healthy cached agent turn looks like the above: a small
// input_tokens, a large cache_read, and a zero creation.
// If cache_creation is large on EVERY turn, the cache is being
// rebuilt each time and you are paying more, not less.

Warum Trefferraten hinter einem Gateway sinken

Ein Cache befindet sich bei dem Upstream, der ihn erstellt hat, und der Präfixabgleich ist exakt. Diese beiden Tatsachen führen zu drei Fehlerarten, die bei einem direkten Aufruf eines einzelnen Anbieters nie auftreten:

Das Routing hat sich geändert. Wenn aufeinanderfolgende Anfragen bei unterschiedlichen Upstreams landen, findet die zweite keinen Cache — der von der ersten geschriebene Eintrag ist dort, wo die zweite ausgeführt wurde, nicht sichtbar. In Ihren eigenen Logs ist das unsichtbar und zeigt sich nur als Cache-Erstellungsanzahl, die eigentlich ein Lesevorgang hätte sein sollen. Das ist die häufigste Ursache und der Grund, warum ein Gateway, das frei zwischen Upstreams umleitet, pro Token günstiger, aber pro Sitzung teurer sein kann.

Vor Ihrem Präfix wurde etwas eingefügt. Eine Schicht, die die Systemnachricht umschreibt, Tool-Definitionen normalisiert oder Felder neu sortiert, erzeugt ein anderes Präfix; ein anderes Präfix bedeutet einen Cache-Miss. Es tritt kein Fehler auf, nur die Rechnung steigt.

Die Lücke war länger als die Lebensdauer des Eintrags. Ein Agent, der zwischen den Runden mehrere Minuten nachdenkt, kann den Cache jedes Mal neu aufbauen. Dies ist eine Eigenschaft Ihres Workloads und nicht des Gateways, wirkt sich aber schlecht mit dem ersten Punkt zusammen aus: Ein Neuaufbau ist zugleich eine Gelegenheit für ein erneutes Routing.

Die Diagnose ist für alle drei Fälle gleich — beobachten Sie cache_creation_input_tokens über eine Sitzung hinweg. Gleichbleibend und groß bedeutet, dass Sie den Cache neu aufbauen. Einmal groß und danach null bedeutet, dass er funktioniert. Bei Kunavo finden Sie Kosten auf Anfrageebene und die Anzahl gecachter Tokens in der Nutzungsansicht; die Caching-Referenz enthält die Details auf Endpunktebene.

Was Sie dagegen tun können

Halten Sie das gecachte Präfix wirklich stabil — setzen Sie alles, was sich pro Anfrage ändert, nach den markierten Block, niemals davor. Bündeln Sie die Runden eines Agents nach Möglichkeit enger, denn Leerlaufzeit ist der Feind eines kurzlebigen Eintrags. Und messen Sie eine Sitzung durchgängig statt nur eine Anfrage: Caching ist eine Eigenschaft einer Sequenz, und eine Schätzung pro Anfrage kann es nicht erkennen. Der Claude-Tokenkostenrechner enthält aus genau diesem Grund ein Feld für gecachte Tokens — setzen Sie es auf den Anteil Ihres Prompts, der sich tatsächlich wiederholt, und der Monatsbetrag ist nicht länger fiktiv.

Häufig gestellte Fragen