Prompt-Caching

Bei einem System-Prompt mit 30.000 Tokens kostet ein Cache-Lesevorgang mit Claude Sonnet 5 $0.14 / 1M statt $1.4 / 1M. Für einen Agenten, der denselben Kontext 50-mal pro Sitzung erneut sendet, senkt der Cache die Eingabekosten um ~90 %.

So aktivieren Sie es

Fügen Sie bei einem beliebigen Systemblock, einer Nachricht oder einer Tool-Definition einen cache_control: { type: "ephemeral" }-Grenzpunkt hinzu. Beim ersten Aufruf speichert das Modell den Bereich bis zu diesem Grenzpunkt im Cache. Nachfolgende Aufrufe mit denselben Präfix-Bytes greifen auf den Cache zu.

from openai import OpenAI

client = OpenAI(
    api_key="sk-kn-...",
    base_url="https://api.kunavo.com/v1",
)

# Mark the large, stable prefix once with cache_control.
# Every subsequent call that sends the same prefix reads it back
# from cache at 0.10× the input rate on Claude Sonnet 5.
# Per-model rates are in the pricing table below.
SYSTEM = [
    {
        "type": "text",
        "text": open("long_system_prompt.txt").read(),
        "cache_control": {"type": "ephemeral"},
    },
]

resp = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[
        {"role": "system", "content": SYSTEM},
        {"role": "user", "content": "Summarize the doc above in 3 bullets."},
    ],
)

u = resp.usage
# OpenAI-compat fields populated by Kunavo:
# - prompt_tokens_details.cached_tokens — read from cache
# - cache_creation_input_tokens          — written to cache this call
print(u.prompt_tokens_details.cached_tokens,
      getattr(u, "cache_creation_input_tokens", 0))

Identisches Wire-Format wie bei der nativen Messages API — cache_control wird unverändert an Claude weitergeleitet:

# Native Anthropic Messages API — cache_control passes through untranslated.
curl https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer $KUNAVO_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "system": [
      {
        "type": "text",
        "text": "<your large stable system prompt>",
        "cache_control": { "type": "ephemeral" }
      }
    ],
    "messages": [
      { "role": "user", "content": "Summarize the doc above in 3 bullets." }
    ],
    "max_tokens": 1024
  }'

Automatische Grenzpunkte an den Endpunkten im OpenAI-Format

Die OpenAI-Formate Chat Completions und Responses haben überhaupt kein Feld cache_control — OpenAI speichert implizit auf seinen eigenen Servern zwischen. Claude tut das nicht: Es speichert nur, was durch einen Grenzpunkt markiert ist. Ein Client, der OpenAI verwendet, kann daher kein Caching anfordern. Bei einer direkten Übersetzung der Anfrage an Claude werden keine Grenzpunkte übermittelt — dadurch wird bei jeder Runde eines langen Chats der gesamte Verlauf erneut zum vollen Eingabepreis berechnet.

Wenn Sie also über /v1/chat/completions oder /v1/responses ein Claude-Modell aufrufen, setzt Kunavo die Grenzpunkte, die das Protokoll nicht übertragen kann. Sie müssen nichts aktivieren. Dies gilt nur für Claude-Modelle — alle anderen Modellfamilien werden über ein Protokoll bedient, bei dem der Anbieter implizit zwischenspeichert und keine Grenzpunkte gesetzt werden müssen.

# Plain OpenAI Chat Completions — no cache_control anywhere in the body.
# The format has no field for one; Kunavo inserts the breakpoints instead.
resp = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[
        {"role": "system", "content": LONG_SYSTEM_PROMPT},
        {"role": "user", "content": "first question"},
        {"role": "assistant", "content": "...previous answer..."},
        {"role": "user", "content": "follow-up"},
    ],
)

u = resp.usage
# Turn that writes the cache:
#   u.cache_creation_input_tokens            -> 18,000
#   u.prompt_tokens_details.cached_tokens    ->      0
# Next turn, same prefix, inside the 5-minute window:
#   u.cache_creation_input_tokens            ->    240   (only the new turn)
#   u.prompt_tokens_details.cached_tokens    -> 18,000
#
# Both stuck at 0 on a conversation well over the threshold? The prefix is
# changing between calls — a timestamp or request id inside the cached span.

Wo sie gesetzt werden und in welcher Reihenfolge das Kontingent aufgebraucht wird:

• Ein fortlaufender Grenzpunkt bei der letzten Nachricht — am letzten Inhaltsblock der letzten Nachricht, sodass alles davor zwischengespeichert wird; endet die Anfrage mit einer Systemnachricht, die in der Konversation bleibt (siehe unten), stattdessen am Block direkt vor dieser Nachricht. Er wird erst hinzugefügt, wenn bereits eine Assistentenantwort in messages vorliegt: Ein Cache-Schreibvorgang wird mit 1.25× Eingabe berechnet. Einen Prompt zu markieren, den niemand erneut sendet, kostet daher ein Viertel mehr und spart nichts. Eine vorherige Assistentenantwort ist ein Anzeichen dafür, dass genau dieses Präfix erneut gesendet wird.
• Ein Grenzpunkt auf system und einer auf tools — am stabilen Anfang des Prompts. Es lohnt sich, ihn auch bei einem einmaligen Aufruf zu markieren, denn wer einen System-Prompt einmal sendet, sendet beim nächsten Aufruf fast immer denselben.
• Vor einer Systemnachricht, die in der Konversation bleibt — was der fortlaufende Grenzpunkt und die Grenzpunkte auf system und tools vom Kontingent übrig lassen, am Block direkt vor der letzten solchen Nachricht, auf die noch etwas folgt, danach vor der davor. Wird zuletzt gefüllt, weil nur ein Client, der eine solche Nachricht von Runde zu Runde verschiebt, diese Position braucht; eine Konversation ohne eine solche Nachricht, also fast jede, hat diese Position nicht.

Zwei Grenzen bestimmen die Einschränkungen. Bei weniger als 8.192 Zeichen im Prompt — Nachrichten, system und Tool-Schemas zusammengenommen — wird überhaupt nichts eingefügt: Anthropic ignoriert Grenzpunkte auf Präfixen unterhalb der eigenen Mindestlänge für das Caching (1.024 Tokens, 2.048 bei Haiku) stillschweigend und berechnet weder Schreib- noch Lesevorgang. Ein Grenzpunkt an dieser Stelle würde also nichts bewirken. Außerdem akzeptiert Anthropic höchstens 4 Grenzpunkte pro Anfrage — ein fünfter führt zu einem harten 400-Fehler und wird nicht stillschweigend ignoriert.

Eine System- oder Developer-Nachricht, die nach der ersten Antwort des Modells gesendet wird, bleibt in der Konversation, und zwar in der Runde, in der sie gesendet wurde, statt in system verschoben zu werden: Das würde in der Runde, in der sie hinzukommt, den Anfang des Prompts ändern und den gesamten Verlauf erneut in den Cache schreiben. Claude erhält sie als Systemnachricht, wo der Upstream eine solche annimmt, und sonst als Text in dieser Nutzerrunde zwischen <system-reminder>-Tags. Eine Systemnachricht, die vor der ersten Antwort des Modells gesendet wird, oder eine, deren eigener Grenzpunkt den Ein-Stunden-Cache anfordert, landet weiterhin in system.

An der Berichterstattung ändert sich nichts: Dieselben Felder cached_tokens und cache_creation_input_tokens, die unter Antwortfelder beschrieben sind, werden ausgefüllt, unabhängig davon, ob die Grenzpunkte von Ihnen oder vom Gateway stammen. Am Nutzungsobjekt können Sie daher prüfen, ob ein eingefügter Grenzpunkt tatsächlich zu einem Cache-Treffer geführt hat.

Preise

Die Cache-Tarife leiten sich vom Eingabepreis des jeweiligen Modells ab und folgen den vom Anbieter festgelegten Verhältnissen — maßgeblich sind die Tabellen unten, und jeder darin angegebene Tarif wird anhand des Eingabepreises des Modells berechnet, nicht manuell eingetragen. Cache-Lesezugriffe werden bei Anthropic und OpenAI mit 0.10× des Eingabepreises berechnet, mit 2 Ausnahmen: 0.025× on Claude Fable 5.1, 0.05× on Claude Opus 5.5. Cache-Schreibvorgänge werden bei allen Claude-Modellen mit 1.25× des Eingabepreises berechnet und bei GPT-6 Astra, GPT-6 Sol, GPT-6 Luna, GPT-5.6 Sol und GPT-5.6 Terra. Kunavo berechnet Schreibvorgänge mit einer TTL von 1 Stunde bei Claude ebenfalls mit 1.25× und liegt damit unter Anthropic mit 2×. Für alle anderen Modelle gibt es keinen separaten Schreibpreis: Schreibvorgänge werden zum normalen Eingabepreis berechnet. In beiden Fällen ist ein Präfix, das auch nur einmal wiederverwendet wird, im Cache günstiger als bei erneuter ungespeicherter Übermittlung. Für jede Tarifklasse gilt derselbe Rabatt des jeweiligen Modells, sodass die Cache-Preise gegenüber der Preisliste des Anbieters im selben Maß rabattiert sind wie die Ein- und Ausgabepreise.

Affinitätsrouting hält den Cache warm

Prompt-Caches beim vorgelagerten Anbieter gelten jeweils pro API-Schlüssel. Wenn jede Anfrage einem zufälligen API-Schlüssel des vorgelagerten Anbieters zugewiesen wird, beträgt die Cache-Trefferrate ~1/N. Kunavo leitet aus Ihrem System-Prompt + der ersten Benutzernachricht einen stabilen Hash ab und leitet alle Aufrufe mit demselben Präfix an denselben API-Schlüssel des vorgelagerten Anbieters weiter — mithilfe von gewichtetem Rendezvous-Hashing, sodass bei Änderungen am Pool nur ~1/N der Schlüssel neu zugeordnet werden.

Sie müssen nichts konfigurieren. Das Affinitätsrouting wird automatisch auf alle Chat-Aufrufe angewendet. (Bild-, Video- und TTS-Aufrufe verwenden zufälliges Routing — für diese Modalitäten gibt es keinen Cache pro Schlüssel.)

Dashboard-Kennzahlen

Sobald Ihre Aufrufe den Cache nutzen, zeigt /app/usage für den ausgewählten Zeitraum zwei aggregierte Kennzahlen an:

• Trefferquote — gecachte Eingabetokens ÷ gesamte Eingabetokens. Exakte Berechnung anhand der Tokenzahlen pro Aufruf.
• Einsparungen — die in diesem Zeitraum eingesparten USD, berechnet pro Modell anhand des tatsächlichen Cache-Lesezugriffstarifs (keine pauschalen Durchschnittswerte). Dies ist eine Schätzung zu Katalogpreisen — da tatsächliche Rechnungen mindestens dem Katalogpreis entsprechen und Aufrufe mit Cache-Treffern unter dem Mindestpreis liegen können, stellt der Wert eine enge Obergrenze für die tatsächlichen Einsparungen dar. Bei typischen Chat-Workloads liegen beide Werte nur wenige Prozent auseinander.

Auf der Detailseite jedes Aufrufs (/app/usage/<id>) werden die Tokenzahlen für Cache- und Cache-Schreibzugriffe angezeigt, sofern sie ungleich null sind, ebenso wie der tatsächlich berechnete Betrag.

Antwortfelder

Kunavo gibt Cache-Tokens in beiden Antwortformaten aus. Am OpenAI-kompatiblen Endpunkt /v1/chat/completions:

An der nativen Messages API unter /v1/messages werden die Originalfelder von Anthropic unverändert durchgereicht:

Nächste Schritte

• Referenz zur Messages API — natives Anthropic-Format mit ausgearbeiteten Cache-Beispielen.
• Claude-Prompt-Caching — die Zahlen im Nutzungsobjekt, anhand derer Sie einen Cache diagnostizieren, und die drei Arten, wie Routing über ein Gateway die Trefferquote beeinträchtigt.
• Abrechnung und Buchungen — wie der cachebewusste max()-Mindestpreis mit den Upstream-Kosten zusammenspielt.
• Vollständige Preistabelle — Preise für neue Eingaben und Ausgaben aller Chat-Modelle, mit der Cache-Untertabellen am Ende.