GPT Prompt Caching

​

Schnellstart

curl https://aihubmix.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -d '{
    "model": "gpt-5.6-sol",
    "prompt_cache_key": "my-app-report-assistant-v1",
    "messages": [
      {
        "role": "system",
        "content": "You are a meticulous assistant for analyzing quarterly financial reports... [Hier feste lange Anweisungen oder Referenzmaterial platzieren, ≥1024 Token]"
      },
      {
        "role": "user",
        "content": "Summarize the key figures in one sentence."
      }
    ]
  }'

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AIHUBMIX_API_KEY"],  # Key wird aus der Umgebungsvariable gelesen
    base_url="https://aihubmix.com/v1",
)

long_context = "You are a meticulous assistant for analyzing quarterly financial reports... [Feste lange Anweisungen oder Referenzmaterial, ≥1024 Token]"

# Dieselbe Anfrage mit identischem Präfix zweimal senden, die zweite trifft den Cache
for i in range(2):
    completion = client.chat.completions.create(
        model="gpt-5.6-sol",
        prompt_cache_key="my-app-report-assistant-v1",
        messages=[
            {"role": "system", "content": long_context},
            {"role": "user", "content": "Summarize the key figures in one sentence."},
        ],
    )
    print(completion.usage.prompt_tokens_details)

// 1. Aufruf: kein Hit
"prompt_tokens_details": {"audio_tokens": 0, "cached_tokens": 0}

// 2. Aufruf: Präfix trifft den Cache
"prompt_tokens_details": {"audio_tokens": 0, "cached_tokens": 2816}

​

Cache-Abrechnung

​

So greift der Cache automatisch

1. Erreicht das Präfix 1.024 Token und wird ein übereinstimmendes Cache-Präfix gefunden, wird der getroffene Teil zum Cache-Lesepreis abgerechnet und die Latenz bis zum ersten Token sinkt;
2. Wird keines gefunden, wird die Anfrage als regulärer Input verarbeitet und das Präfix in den Cache geschrieben (ab GPT-5.6 mit 1,25x Write-Gebühr);
3. Ein Hit setzt voraus, dass das Präfix Byte für Byte identisch ist; jede Änderung im Präfix invalidiert den gesamten Cache ab dieser Position.

• Feste lange System-Anweisungen oder umfangreiche Few-Shot-Beispiele
• Wiederholt referenziertes langes Referenzmaterial in RAG-Szenarien
• Agent-Workflows mit umfangreichen Tool-Definitionen (tools)
• Lange Multi-Turn-Konversationen, die Nachrichten nur hinten anfügen

​

GPT-5.6-Cache-Parameter

1. Standard (implicit-Modus): Auch ohne Cache-Parameter wird automatisch in den Cache geschrieben – das System setzt den Breakpoint automatisch an die Position der neuesten Nachricht. Ab GPT-5.6 werden auch automatisch ausgelöste Cache-Writes mit 1,25x abgerechnet.
2. implicit-Modus + explizite Breakpoints: Zusätzlich zum automatischen Breakpoint kann prompt_cache_breakpoint auf Content-Blöcken gesetzt werden, um die Cache-Grenze am Ende des stabilen Inhalts zu fixieren; Änderungen am Inhalt hinter dem Breakpoint invalidieren den Präfix-Cache vor dem Breakpoint nicht.
3. explicit-Modus: Ist prompt_cache_options.mode auf "explicit" gesetzt, werden nur manuelle Breakpoints verwendet; ganz ohne Breakpoints nutzt die Anfrage keinen Cache und erzeugt keine Cache-Write-Gebühr. Offizieller Wortlaut: “If the conversation contains no explicit breakpoints, the request does not use prompt caching or incur cache-write charges.”

{
  "model": "gpt-5.6-sol",
  "prompt_cache_options": {"mode": "explicit"},
  "messages": [
    {"role": "user", "content": "[Einmaliger langer Inhalt ohne Wiederverwendung]"}
  ]
}

{
  "model": "gpt-5.6-sol",
  "prompt_cache_key": "my-app-report-assistant-v1",
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "[Feste lange Anweisungen oder Referenzmaterial, ≥1024 Token]",
          "prompt_cache_breakpoint": {"mode": "explicit"}
        }
      ]
    },
    {"role": "user", "content": "Summarize the key figures in one sentence."}
  ]
}

• Pro Anfrage werden maximal 4 neue Cache-Writes erstellt; im implicit-Modus belegt der automatische Breakpoint einen davon;
• Das Präfix vor einem Breakpoint muss weiterhin 1.024 Token erreichen, um gecached zu werden;
• Beim Lesen wird unter den letzten 50 Breakpoints das längste passende Präfix verwendet;
• Ein Breakpoint auf einem nicht unterstützten Content-Block liefert 400 invalid_request_error. Chat Completions unterstützt die Blöcke text / image_url / input_audio / file / refusal, die Responses API die Blöcke input_text / input_image / input_file.

​

Warum der Cache nicht getroffen wird

• Präfix unter 1.024 Token: Anfragen unterhalb der Mindest-Cache-Länge werden als regulärer Input verarbeitet;
• Veränderlicher Inhalt im Präfix: Zeitstempel, Session-IDs, Benutzervariablen usw. gehören hinter den festen Inhalt; jede Änderung im Präfix invalidiert den nachfolgenden Cache;
• Geänderte tools-Definitionen oder -Reihenfolge: Die Tool-Liste geht in die Präfix-Berechnung ein; Definitionen und Reihenfolge müssen exakt übereinstimmen;
• Inkonsistenter detail-Parameter bei Bildern: detail beeinflusst die Tokenisierung von Bildern und muss gleich bleiben;
• Geändertes Schema für strukturierte Ausgaben: Das JSON-Schema aus response_format geht als Präfix der System-Nachricht in den Cache ein; eine Schema-Änderung ist eine Präfix-Änderung;
• Geändertes reasoning_effort: offiziell als häufige Ursache für eine niedrigere Cache-Trefferrate aufgeführt (“Changes to reasoning effort”);
• Cache-Aufbewahrung überschritten: Vor GPT-5.6 Löschung nach 5–10 Minuten Inaktivität, ab GPT-5.6 mindestens 30 Minuten Aufbewahrung;
• prompt_cache_key nicht gesetzt (GPT-5.6): Ohne den Parameter sind automatische Hits weiterhin möglich, aber ohne das zuverlässigere Matching.

​

Best Practices

• Festen Inhalt (System-Anweisungen, Beispiele, Referenzmaterial, Tool-Definitionen) an den Anfang der Anfrage setzen, den sich pro Runde ändernden Inhalt ans Ende;
• Für Traffic mit demselben Präfix denselben stabilen prompt_cache_key verwenden; den Gesamtverkehr pro Key bei etwa 15 Anfragen/Minute halten und bei Überschreitung nach Anwendungsbereich auf weitere Keys aufteilen;
• In Multi-Turn-Konversationen Nachrichten nur hinten anfügen und Verlaufsnachrichten nicht ändern;
• Für Anfragen mit demselben Präfix kontinuierlichen Traffic aufrechterhalten, um Cache-Löschungen zu reduzieren;
• Bei einmaligen langen Anfragen ohne Präfix-Wiederverwendung die Cache-Write-Gebühr mit dem explicit-Modus vermeiden (ab GPT-5.6);
• Die Hit-Rate laufend über usage.prompt_tokens_details.cached_tokens überwachen.

​

Häufig gestellte Fragen (FAQ)

​

Muss Prompt Caching bei GPT manuell aktiviert werden?

​

Wie wird die Cache-Write-Gebühr bei GPT-5.6 berechnet? Wie vermeide ich unnötige Write-Gebühren?

​

Wie lange bleibt der Cache erhalten?

​

Was unterscheidet die expliziten Breakpoints von GPT-5.6 von Claudes cache_control?

​

Beeinflusst Caching den Output?

​

Offizielle Referenzen

• GPT-5.6-Release-Ankündigung: Abrechnungsregel 1,25x für Cache-Writes / 90 % Rabatt für Reads
• Prompt-Caching-Leitfaden: Mechanismus, Parameter, usage-Felder und Grenzen
• OpenAI Pricing: Offizielle Listenpreise der Modelle
• GPT-5.6-Modelldokumentation: Kontextfenster, Abrechnungsschwelle für langen Kontext