Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du
.md an die URL der Seite anhängst.
Wenn mehrere Anfragen mit demselben Prompt-Präfix beginnen, kann das Modell dank Prompt-Caching auf bereits geleistete Rechenarbeit zurückgreifen. Das hat drei wesentliche Vorteile:
Weniger Rechenaufwand: Das Modell muss ein bereits verarbeitetes Prompt-Präfix nicht erneut berechnen.
Günstigere Eingabetoken: Für wiederverwendete Token zahlst du den reduzierten Preis des Modells für Eingaben aus dem Cache und sparst bis zu 95 %.
Schnellere Antworten: Das Modell braucht weniger Zeit, um die Eingabe zu verarbeiten, bevor die Antwort beginnt.
Bei unterstützten OpenAI-Modellen ist Prompt-Caching standardmäßig aktiviert. Im Dashboard für Prompt-Caching kannst du die Trefferquote bei Cache-Lesezugriffen verfolgen. Mit dem Diagnosetool für Prompt-Caching kannst du herausfinden, warum Cache-Treffer ausbleiben, und die Wiederverwendung verbessern.
Bei Modellaufrufen über die Agents API funktioniert Prompt-Caching genauso wie bei der Responses API. Wenn du Kontext innerhalb einer Sitzung wiederverwendest, kann ein gemeinsames Prompt-Präfix erhalten bleiben. Eine fortlaufende Sitzung garantiert jedoch keinen Cache-Treffer. Informationen zu den Nutzungsfeldern einer Sitzung und zur Erfassung der Nutzung durch Subagenten findest du unter Beobachtbarkeit und Nutzung.
Die Preise für Prompt-Caching hängen vom Modell ab. Die aktuellen Preise für Eingaben aus dem Cache und für Schreibzugriffe findest du in der API-Preisübersicht. Für jedes Eingabetoken gilt genau einer der drei Preise: der reguläre Eingabepreis, der Preis für Eingaben aus dem Cache oder der Schreibpreis.
Was speichert das Prompt-Caching?
Bei der Verarbeitung von Eingabetoken berechnet das Modell Zwischenzustände, sogenannte Key-Value-Zustände (KV-Zustände). Damit kann es auf frühere Token zurückgreifen, während es neue Eingaben verarbeitet und Ausgabetoken erzeugt.
Prompt-Caching speichert diesen Zustand für ein wiederverwendbares Präfix, also für die unveränderten Token am Anfang eines Prompts. Beginnt eine spätere Anfrage mit demselben Präfix und findet sich ein passender Cache-Eintrag, kann das Modell den gespeicherten Zustand nutzen, ohne diese Token erneut zu verarbeiten. Neue Eingaben muss es weiterhin verarbeiten, um eine neue Antwort zu erzeugen.
Beim Prompt-Caching werden Key-Value-Tensoren (KV-Tensoren) gespeichert, nicht die Token selbst.
Für die Wiederverwendung muss das gesamte Präfix in der Form übereinstimmen, in der es dem Modell vorliegt. Ändert sich vor einem Haltepunkt der Inhalt oder eine relevante Einstellung, passt das Präfix ab dieser Änderung nicht mehr zum vorhandenen Cache-Eintrag.
Verborgene Systemnachricht
Anweisungen von OpenAI
Tools
Definitionen und Schemata
Entwicklernachricht
Anweisungen der Anwendung
Kontextverlauf
Nachrichten aus der Unterhaltung, Tool-Aufrufe und deren Ergebnisse sowie Text und multimodale Inhalte
Wenn du eine Anfrage änderst, geht ein vorhandener Cache-Eintrag nicht zwangsläufig verloren. Entscheidend ist, ob die nächste Anfrage dasselbe Präfix enthält und bei der Suche ein passender, zulässiger Haltepunkt gefunden wird. Prüfe vor allem diese Einstellungen:
Kann die internen Reasoning-Anweisungen des Modells ändern. Bei unterstützten Modellen kannst du den Reasoning-Aufwand mit einer Konfigurationsaktualisierung ändern und dabei das bisherige Präfix beibehalten.
Ersetzt frühere Gesprächsinhalte durch verdichteten Kontext. Das kann die Wiederverwendung ab dem ersten geänderten Token verhindern.
So funktioniert das Caching
Ein Cache-Haltepunkt markiert das Ende eines Prompt-Präfixes, das OpenAI im Cache speichern und bei späteren Anfragen wiederverwenden kann. Die erste Anfrage schreibt ein geeignetes Präfix in den Cache. Bei späteren Anfragen sucht OpenAI nach dem längsten verfügbaren Präfix, das mit der Eingabe übereinstimmt. Dazu prüft OpenAI die zulässigen Haltepunkte von hinten nach vorn, bis sich ein Treffer ergibt.
Damit sich ein Prompt-Präfix im Cache speichern lässt, muss es die Mindestanzahl an Token für das Caching erreichen, die das Modell vorgibt. Token in den verborgenen Systeminhalten von OpenAI zählen dabei nicht mit. Ab GPT-5.6 liegt die Mindestlänge bei 1.024 Token. Bei früheren Modellen hängt sie von den Einstellungen der Anfrage ab. Einzelheiten findest du im Modellvergleich.
Sobald die Mindestlänge erreicht ist, kannst du Cache-Haltepunkte explizit setzen oder sie implizit von OpenAI setzen lassen. Welche Möglichkeiten du hast, hängt vom Modell ab.
Ab GPT-5.6 kosten Schreibzugriffe bei der Standardlaufzeit von 30 Minuten das 1,25-Fache des regulären Preises für Eingabetoken ohne Caching. In der Responses API kannst du eine Mindestlaufzeit von 12 Stunden wählen. Dann kostet ein Schreibzugriff das 2,5-Fache des regulären Eingabepreises. Spätere Lesezugriffe kosten bei den meisten dieser Modelle das 0,1-Fache des regulären Eingabepreises, bei GPT-6.1 Sol und GPT-6.1 Terra das 0,05-Fache. Das gilt unabhängig von der gewählten Laufzeit.
Bei einem Lesepreis von 10 % des regulären Eingabepreises und einer Laufzeit von 30 Minuten kostet es insgesamt das 1,35-Fache des regulären Eingabepreises, ein Präfix einmal zu schreiben und einmal vollständig wiederzuverwenden. Zweimaliges Verarbeiten ohne Caching kostet das Doppelte. Bei zehn Anfragen mit einem Schreibzugriff und neun vollständigen Lesezugriffen zahlst du zu diesem Preis das 2,15-Fache, ohne Caching das Zehnfache.
Diese Modelle unterstützen implizites und explizites Caching. Beim expliziten Caching kannst du genauer steuern, welchen Kontext OpenAI in den Cache schreibt.
Expliziter Modus: Du setzt die Cache-Haltepunkte passend dazu, wie du deinen Kontext verwaltest.
Setze prompt_cache_options.mode auf explicit, um ausschließlich selbst gewählte Haltepunkte zu verwenden. Markiere jeden gewünschten Haltepunkt, indem du prompt_cache_breakpoint: { "mode": "explicit" } zu einem unterstützten Inhaltsblock in einer Eingabenachricht hinzufügst.
Wenn du keine expliziten Haltepunkte setzt, nutzt die Anfrage kein Prompt-Caching und schreibt nichts in den Cache.
Im rein expliziten Modus bestimmst du, wo Schreibzugriffe enden. Für Inhalte nach dem letzten gewählten Haltepunkt gilt der reguläre Eingabepreis ohne Schreibgebühr. So vermeidest du Schreibzugriffe für wechselnde Inhalte, die du wahrscheinlich nicht wiederverwendest.
Mit mehreren expliziten Haltepunkten kannst du Präfixe beibehalten, deren Inhalte sich unterschiedlich häufig ändern. Pro Anfrage sind bis zu vier Schreibzugriffe möglich.
Eingabeelemente vom Typ additional_tools unterstützen prompt_cache_breakpoint derzeit nicht.
In instructions auf oberster Ebene kannst du keinen expliziten Haltepunkt setzen. Um wiederverwendbare Entwickleranweisungen zu markieren, füge sie als input_text-Block in eine Entwicklernachricht ein.
Impliziter Modus: OpenAI setzt die Haltepunkte automatisch an Stellen, die sich für die meisten Anwendungsfälle eignen.
Wenn prompt_cache_options.mode auf implicit steht, setzt OpenAI einen Haltepunkt am Ende der letzten zulässigen Nachricht. Zulässig sind:
Nutzernachrichten
die letzte Toolantwort in einem Block unmittelbar aufeinanderfolgender Toolantworten
die letzte Entwicklernachricht im anfänglichen Block unmittelbar aufeinanderfolgender Entwicklernachrichten.
Du kannst explizite Haltepunkte hinzufügen und den impliziten Haltepunkt beibehalten. Der implizite Haltepunkt belegt einen der vier möglichen Schreibzugriffe. Damit bleiben drei für explizite Haltepunkte verfügbar.
Diese Modelle unterstützen ausschließlich implizites Caching. OpenAI setzt implizite Haltepunkte in modellabhängigen Abständen, gemessen ab dem Anfang der verborgenen Systemnachricht von OpenAI. Für das Caching kommen nur Haltepunkte infrage, die ab dem Ende des verborgenen Kontexts gemessen mindestens die erforderliche Präfixlänge erreichen.
Für den gemeldeten Wert von cached_tokens zieht OpenAI von der Tokenanzahl bis zum letzten übereinstimmenden Haltepunkt die verborgenen Systemtoken ab und rundet das Ergebnis auf ein Vielfaches von 128 ab.
So findet OpenAI passende Präfixe
OpenAI prüft in der eingehenden Anfrage nur bestimmte Präfixgrenzen für die Cache-Suche, die im Folgenden beschrieben sind. Die Suche beginnt beim längsten Präfix und geht bis zum kürzesten. Gesucht wird ein passendes Präfix, das auf dem jeweiligen Rechner bereits im Cache verfügbar ist.
Ab GPT-5.6 prüft OpenAI in der eingehenden Anfrage folgende Stellen:
Rein expliziter Modus: die ersten 2 und die letzten 50 expliziten Haltepunkte.
Impliziter Modus: die ersten 2 und die letzten 50 expliziten Haltepunkte, den impliziten Haltepunkt, das Ende von bis zu 20 früheren zulässigen Nachrichten und das Ende des anfänglichen Blocks unmittelbar aufeinanderfolgender Entwicklernachrichten. So lässt sich im impliziten Modus auch ein Präfix wiederverwenden, das mit einer früheren Nachricht endet, ohne dass dort ein expliziter Haltepunkt gesetzt wurde.
Modellgeneration
Caching-Modus
Das System setzt implizite Breakpoints bei der letzten dafür geeigneten Nutzernachricht.
Verborgener SystemkontextToolsEntwicklerrolleKontextverlaufFolgeanfrageEingabe aus dem CacheEingabe ohne Cache-Treffer
Mindestlänge für das Caching (modellabhängig)
Anfrage 1
12,000 Eingabetoken
3,000 Token(zur Veranschaulichung)
▼
Anfrage 2
15,000 Eingabetoken
3,000 Token(zur Veranschaulichung)
▼
0
2.5k
5k
7.5k
10k
12.5k
15k
17.5k
20k
Eingabetoken (einschließlich der beispielhaft dargestellten verborgenen Token)
Cache-Einträge bleiben nur begrenzte Zeit gespeichert. Die Mindestlaufzeit, die Aufbewahrungseinstellungen und das Verhalten bei der Wiederverwendung eines Präfixes hängen vom Modell ab.
In der Responses API legst du mit prompt_cache_options.ttl die Mindestlaufzeit fest:
Wert
Mindestlaufzeit
Preis für Schreibzugriffe
Geeignet für
"30m" (Standard)
30 Minuten
1,25-Faches des regulären Eingabetokenpreises ohne Caching
Gespräche und Agentenschritte, die Kontext häufig wiederverwenden.
"12h"
12 Stunden
2,5-Faches des regulären Eingabetokenpreises ohne Caching
Stabile Anweisungen oder Referenzmaterial zur Wiederverwendung nach längeren Pausen.
Die angegebenen Schreibpreise sind Gesamtpreise. Der reguläre Eingabepreis kommt nicht hinzu. Für Lesezugriffe gilt bei beiden Laufzeiten derselbe Preis. OpenAI kann Einträge länger als die angeforderte Mindestlaufzeit aufbewahren. "12h" legt keinen Löschzeitpunkt fest und ändert die Aufbewahrungsrichtlinie zur maximalen Speicherdauer nicht.
Der Wert von ttl auf Anfrageebene gilt für den impliziten Haltepunkt und für explizite Haltepunkte ohne eigenen ttl-Wert. Mit prompt_cache_breakpoint.ttl kannst du die Laufzeit für einen einzelnen expliziten Haltepunkt überschreiben. Lässt du beide Einstellungen weg, gilt weiterhin der Standardwert "30m". Bei nicht unterstützten Werten gibt die API 400 invalid_request_error zurück. Diese Einstellungen ändern den Parameter prompt_cache_retention früherer Modelle nicht.
Laufzeiten in einer Anfrage kombinieren
Platziere Material, das du im Laufe des Tages immer wieder verwendest, am Anfang des Prompts und weise seinem Haltepunkt die Laufzeit "12h" zu. Verwende "30m" für Sitzungskontext, der sich häufiger ändert. Im Beispiel beträgt die Standardlaufzeit für die Anfrage 30 Minuten. Für das gemeinsame Präfix wird sie überschrieben. Im rein expliziten Modus steht die aktuelle Frage hinter dem letzten Haltepunkt, sodass für ihren Inhalt keine Schreibgebühr anfällt.
Anfrage an die Responses API mit Haltepunkten für 12 Stunden und 30 Minuten
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30{"model": "gpt-6.1-sol","prompt_cache_options": { "mode": "explicit", "ttl": "30m" },"input": [ {"role": "developer","content": [ {"type": "input_text","text": "Shared instructions and reference material reused throughout the day...","prompt_cache_breakpoint": { "mode": "explicit", "ttl": "12h" } } ] }, {"role": "user","content": [ {"type": "input_text","text": "Session context reused over the next few minutes...","prompt_cache_breakpoint": { "mode": "explicit" } }, {"type": "input_text","text": "The current question, which does not need a cache write..." } ] } ]}
Ersetze den Platzhaltertext durch deine Inhalte. Jedes Präfix, das du im Cache speichern möchtest, muss die Mindestlänge für das Caching des Modells erreichen.
Überlappende Schreibzugriffe und Änderungen der Laufzeit
Ein Haltepunkt umfasst das gesamte Präfix bis zu dieser Stelle. Innerhalb einer Anfrage wird jedes Token einmal abgerechnet. Dabei gilt die längste Laufzeit aller ausgewählten Schreibzugriffe, die dieses Token umfassen. Ein weiter hinten gesetzter Haltepunkt mit 12 Stunden Laufzeit gibt früheren ausgewählten Haltepunkten innerhalb desselben Präfixes ebenfalls eine Laufzeit von 12 Stunden.
Die Beispiele setzen voraus, dass jedes bereits gespeicherte Präfix an einer für die Cache-Suche zulässigen Stelle in der neuen Anfrage endet und mit deren Inhalt übereinstimmt.
Cache-Zustand vor der Anfrage
Gewählte Haltepunkte
Als Lesezugriff abgerechnete Token
Als 30-Minuten-Schreibzugriff abgerechnete Token
Als 12-Stunden-Schreibzugriff abgerechnete Token
Kein Präfix im Cache
"12h" bei 2.000 Token, dann "30m" bei 5.000
0
3.000
2.000
Kein Präfix im Cache
"30m" bei 2.000 Token, dann "12h" bei 5.000
0
0
5.000
Gültiger 30-Minuten-Eintrag für die ersten 2.000 Token
"12h" bei 5.000
0
0
5.000
Gültiger 12-Stunden-Eintrag für die ersten 2.000 Token
"30m" bei 5.000
2.000
3.000
0
Wenn du die Laufzeit für Token in einem gültigen 30-Minuten-Eintrag auf 12 Stunden verlängerst, wird für diese Token ein neuer 12-Stunden-Schreibzugriff abgerechnet. Die Kosten des früheren Schreibzugriffs werden nicht angerechnet. Für jeden Teil, den bereits ein gültiger 12-Stunden-Eintrag abdeckt, gilt weiterhin der Lesepreis.
Ein Lesezugriff mit 30 Minuten Laufzeit verlängert die Gültigkeit auf mindestens 30 Minuten ab dem Zugriff. Nutzt er einen gültigen 12-Stunden-Eintrag, gilt der spätere der beiden Zeitpunkte: die bisherige Ablaufzeit oder 30 Minuten nach dem Lesezugriff. Damit beginnt keine neue 12-Stunden-Laufzeit und es fällt keine weitere Schreibgebühr an.
Die Mindestlaufzeit bestimmt, wie lange der Lesepreis für den Cache gelten kann. Sie garantiert weder die Wiederverwendung gespeicherter KV-Tensoren noch eine geringere Latenz bei jeder Anfrage.
Verwende prompt_cache_retention. Welche Werte unterstützt werden, hängt vom Modell ab:
in_memory: Bei Inaktivität bleiben Einträge in der Regel etwa 5 bis 10 Minuten aktiv, höchstens eine Stunde.
24h: Bei verlängerter Aufbewahrung bleiben Einträge in der Regel etwa 30 Minuten verfügbar und können bis zu 24 Stunden gespeichert bleiben.
Standardwerte für die Aufbewahrung und die Einstellung „Keine Datenaufbewahrung“
Beim Prompt-Caching können verschlüsselte Key-Value-Tensoren als Anwendungszustand im lokalen GPU-Speicher abgelegt werden. Bei Modellen, die sowohl in_memory als auch 24h unterstützen, hängt der Standardwert von der Aufbewahrungsrichtlinie deiner Organisation ab:
Für Organisationen ohne aktivierte Einstellung „Keine Datenaufbewahrung“ gilt standardmäßig 24h.
Für Organisationen mit aktivierter Einstellung „Keine Datenaufbewahrung“ gilt standardmäßig in_memory.
Prüfe vor der Auswahl eines Werts, welche Aufbewahrungsrichtlinien für dein Modell und deine Organisation verfügbar sind.
Speicherort des Caches
Jeder Rechner speichert Cache-Zustände lokal. Bei mehr als 15 Anfragen pro Minute können Anfragen auf andere Rechner umgeleitet werden. Eine Anfrage kann ein gespeichertes Präfix nur dann wiederverwenden, wenn sie einen Rechner mit einem passenden, noch gültigen Eintrag erreicht. Deshalb spielt das Routing für die Wiederverwendung eine wichtige Rolle.
OpenAI übernimmt das Routing automatisch. Innerhalb einer Organisation und einer Verarbeitungsregion hängt es für das jeweilige Modell von folgenden Faktoren ab:
Aktuelle Auslastung der Rechner und verfügbare Kapazität.
Hashwert der ersten Token nach den verborgenen OpenAI-Inhalten, einschließlich etwaiger Tooldefinitionen. Wie viele Token in den Hashwert eingehen, hängt vom Modell ab.
Ein mitgegebener prompt_cache_key. Er trennt die Wiederverwendung nach Gruppen von Anfragen und hilft bei Modellen vor GPT-5.6, das Cache-Routing zu optimieren.
Verwende bei Modellen vor GPT-5.6 einen stabilen prompt_cache_key für Anfragen mit demselben wiederverwendbaren Präfix. So lassen sich zusammengehörige Anfragen leichter an denselben Cache leiten. Bei Gruppen mit hohem Anfragevolumen solltest du pro Schlüssel über alle zugehörigen Präfixe hinweg insgesamt etwa 15 Anfragen pro Minute anstreben. Verteile ein höheres Volumen mithilfe einer stabilen, deterministischen Zuordnung auf mehrere Schlüssel. Verwende für zusammengehörige Anfragen denselben prompt_cache_key, damit sie den zugehörigen Cache wiederverwenden können. Schlüssel beeinflussen das Routing. Sie binden Anfragen weder an einen bestimmten Rechner noch garantieren sie einen Cache-Treffer.
Ab GPT-5.6 übernimmt OpenAI das Cache-Routing automatisch. Zur Optimierung des Cachings ist kein Schlüssel erforderlich. Mit unterschiedlichen Schlüsseln kannst du die Cache-Nutzung innerhalb deiner Anwendung für einzelne Kundenkonten oder Personen getrennt erfassen.
Mit getrennten Schlüsseln lässt sich leichter erklären, wie viele Token pro Kundenkonto oder Person aus dem Cache stammen und wie sie abgerechnet werden. Getrennte Schlüssel helfen auch dabei, zu verhindern, dass Personen mit gezielten Test-Prompts anhand von Cache-Treffern herausfinden, ob übereinstimmende Inhalte anderer Personen bereits im Cache lagen. Weitere Informationen findest du unter Cache-Nutzung mit Schlüsseln getrennt erfassen.
Modellunterschiede im Überblick
Verhalten
Ab GPT-5.6
GPT-5.5 und GPT-5.5 Pro
Andere frühere Modelle
Implizite Haltepunkte
Am Ende der letzten zulässigen Nachricht.
In regelmäßigen Abständen von 2.048 Token.
In regelmäßigen, modellabhängigen Abständen.
Explizite Haltepunkte
Unterstützt
Nicht unterstützt
Nicht unterstützt
prompt_cache_key
Optional zur getrennten Erfassung der Cache-Nutzung
Stabilen Schlüssel zur Optimierung des Cache-Routings verwenden
Stabilen Schlüssel zur Optimierung des Cache-Routings verwenden
Mindestlänge für ein Präfix im Cache
1.024 sichtbare Eingabetoken
Abhängig von den Anfrageeinstellungen
Abhängig von den Anfrageeinstellungen
Gemeldete Token aus dem Cache
Exakte Anzahl bis zur zulässigen Präfixgrenze, ohne verborgene Token
Ohne verborgene Token, auf ein Vielfaches von 128 abgerundet
Ohne verborgene Token, auf ein Vielfaches von 128 abgerundet
Preis für Cache-Lesezugriffe
0,1-Faches des regulären Eingabepreises (0,05-Faches bei GPT-6.1 Sol und GPT-6.1 Terra)
Modellabhängiger Preis für Eingaben aus dem Cache
Modellabhängiger Preis für Eingaben aus dem Cache
Preis für Cache-Schreibzugriffe
1,25-Faches für "30m", 2,5-Faches für "12h" in der Responses API
In der Regel 5 bis 10 Minuten bei Inaktivität für in_memory, bis zu 24 Stunden für 24h
* Folgende Modelle unterstützen die verlängerte Aufbewahrung: gpt-5.5, gpt-5.5-pro, gpt-5.4, gpt-5.2, gpt-5.1-codex-max, gpt-5.1, gpt-5.1-codex, gpt-5.1-codex-mini, gpt-5.1-chat-latest, gpt-5, gpt-5-codex und gpt-4.1.
Bei Modellen vor GPT-5.6 hängt die Mindestlänge für das Caching von den Anfrageeinstellungen ab. Dazu gehören Tools, Bilder, Ausgabeschemata, der Reasoning-Aufwand und die Ausführlichkeit der Antwort.
Bei Anwendungen mit mehreren Gesprächsschritten kannst du mehr Eingabetoken einsparen, wenn du den wachsenden Gesprächsverlauf wiederverwendest, als wenn du nur die anfänglichen Anweisungen im Cache speicherst. Behalte frühere Nachrichten und Toolergebnisse bei, damit spätere Schritte das gesamte gemeinsame Präfix nutzen können.
Halte das Präfix stabil. Stelle stabile Entwickleranweisungen und gemeinsames Referenzmaterial an den Anfang. Enthalten die Anweisungen oder das Material Zeitstempel, nutzerspezifische Inhalte oder andere wechselnde Inhalte, platziere diese am Ende oder verschiebe sie in spätere Nachrichten.
Behalte den Gesprächsverlauf bei. Hänge neue Nachrichten an, statt frühere Gesprächsschritte umzuschreiben. Zusammenfassungen, Kontextverdichtung oder das Kürzen des Kontexts können das Präfix so verändern, dass der bisherige Cache-Eintrag nicht mehr passt.
Ändere den Reasoning-Aufwand, ohne das Präfix umzuschreiben. Hänge bei GPT-6-Modellen ein Eingabeelement vom Typ configuration_update an, um den Reasoning-Aufwand zwischen Antworten zu ändern. Lass reasoning.effort auf Anfrageebene unverändert. So bleibt das ursprüngliche Präfix für die Wiederverwendung erhalten. Beispiele und Einschränkungen zur Kompatibilität findest du unter Reasoning-Aufwand im Gespräch ändern.
Wechselnde Inhalte hinter dem Haltepunkt platzieren
Bei unterstützten Modellen ab GPT-6 kannst du ein Eingabeelement vom Typ configuration_update anhängen, um den Reasoning-Aufwand im Gespräch zu ändern und das bisherige Präfix im Cache beizubehalten. Lass reasoning.effort auf oberster Ebene auf dem ursprünglichen Wert. Eine Änderung dieser Einstellung kann dazu führen, dass verborgene Systemanweisungen umgeschrieben werden.
Die jüngste Aktualisierung von reasoning.effort bestimmt den Reasoning-Aufwand für die folgenden Antworten. Hänge dieses Element an input an, um den Reasoning-Aufwand auf high zu setzen.
Wenn deine Anwendung je nach Anfrage andere Tools benötigt, ändere, welche Tools aufrufbar sind. Lass ihre Definitionen unverändert, damit sich Präfixe wiederverwenden lassen.
Halte die Tools konsistent. Behalte Tooldefinitionen, Reihenfolge und Schemata bei.
Deaktiviere Tools für eine Anfrage. Setze tool_choice auf "none", statt die Tooldefinitionen zu entfernen.
Aktiviere nur ausgewählte Tools. Mit allowed_tools schränkst du die aufrufbaren Tools ein, ohne die mitgegebene tools-Liste zu ändern.
Lade Tools bei Bedarf. Verwende die Toolsuche mit defer_loading: true. So verbrauchst du bei den ersten Anfragen eines Threads mit mehreren Gesprächsschritten weniger Eingabetoken für Tooldefinitionen. Gefundene Tools werden am Ende des Kontexts angehängt, sodass frühere wiederverwendbare Inhalte erhalten bleiben.
Behalte den Verlauf der geladenen Tools bei. Mit einem Eingabeelement vom Typ additional_tools in der Entwicklerrolle kannst du während eines Threads Tools entsprechend der Logik deiner Anwendung hinzufügen.
Ab GPT-5.6 bestimmen zwei Einstellungen, wo Cache-Haltepunkte gesetzt werden. Mit prompt_cache_options.mode wählst du zwischen implizitem und rein explizitem Caching. Mit prompt_cache_breakpoint markierst du eine selbst gewählte Präfixgrenze.
Lass Haltepunkte automatisch setzen. Mit implizitem Caching wird am Ende der letzten zulässigen Nachricht ein Haltepunkt gesetzt. Das ist praktisch für Threads, die den vorhandenen Kontext mit jedem Gesprächsschritt erweitern.
Wähle Haltepunkte gezielt aus. Setze explizite Markierungen am Ende stabiler Inhalte. Mit dem rein expliziten Modus vermeidest du unnötige Schreibzugriffe für wechselnde Suffixe.
Shared cached prefix for breakpoint 2
Hidden system message
Tools
Developer message · stable prefix
Developer message · variable suffix A
User message
Tool call
Tool result
Assistant message
Developer message · variable suffix B
New user input A
New user input B
Breakpoint 1
Breakpoint 2
Shared cached prefix for breakpoint 1
Unreused suffix: no cache-write charge
New user inputs: no cache-write charge
Ab GPT-5.6 kannst du bekannten Kontext vorab verarbeiten lassen, um bei einer späteren Anfrage die Zeit bis zum ersten Token zu verkürzen. Eine interaktive Anwendung kann beispielsweise gemeinsame Anweisungen, Tooldefinitionen oder Referenzmaterial schon beim Start in den Cache laden, bevor jemand die erste Frage stellt.
Setze prompt_cache_options.prewarm in einer Anfrage an die Responses API auf true, um den Cache ohne Ausgabe vorzubereiten. Sobald die Anfrage abgeschlossen ist, sende deine eigentliche Anfrage mit demselben Prompt-Präfix. Lass prewarm dabei weg oder setze es auf false.
Verwende ab GPT-5.6 prompt_cache_key, wenn du die Cache-Nutzung in deiner Anwendung nach Kundenkonto, Person oder Workspace getrennt erfassen möchtest. So lassen sich für jede Gruppe die Nutzung von Token aus dem Cache und die Abrechnung leichter nachvollziehen. Der Schlüssel ist optional. Zur Optimierung des Cachings brauchst du ihn bei diesen Modellen nicht.
Lege fest, wie du die Cache-Nutzung trennen möchtest. Vergib für jedes Kundenkonto oder jede Person einen eigenen Schlüssel, wenn du die jeweilige Cache-Nutzung getrennt erfassen möchtest. Beispielsweise trennen support:customer_123 und support:customer_456 die Cache-Nutzung zweier Kundenkonten, selbst wenn ihre Anfragen dasselbe Präfix enthalten.
Halte den Schlüssel innerhalb jeder Gruppe stabil. Verwende für zusammengehörige Anfragen eines Kundenkontos denselben Schlüssel. Erzeuge für eine Sitzung oder einen Thread nur dann einen eigenen Schlüssel, wenn du die Cache-Nutzung dafür separat erfassen möchtest.
Verwende Schlüssel durchgängig. Gib bei allen Anfragen eines Kundenkontos dessen Schlüssel mit, damit die Cache-Nutzung getrennt bleibt. Das hilft auch zu verhindern, dass sich anhand von Cache-Treffern auf Inhalte anderer Kundenkonten schließen lässt.
Bei Modellen vor GPT-5.6 spielt prompt_cache_key eine wichtige Rolle für die Trefferquote. Verwende für Anfragen mit demselben wiederverwendbaren Präfix einen stabilen Schlüssel. So lassen sie sich leichter an denselben Cache leiten. Beachte bei Gruppen mit hohem Anfragevolumen die Hinweise zur Verteilung auf mehrere Schlüssel.
Bei Modellen der Responses API, die prompt_cache_options unterstützen, verwende "30m" für häufig wiederverwendeten Kontext. Für stabile Präfixe, die du nach längeren Pausen erneut nutzt, kommt "12h" infrage. Vergleiche den höheren Schreibpreis für 12 Stunden mit den Kosten für ein erneutes Schreiben nach Ablauf der 30 Minuten. Lege für einzelne Haltepunkte eine abweichende Laufzeit fest, damit gemeinsames Material länger gültig bleibt als sitzungsspezifischer Kontext. Beispiele und Abrechnungsregeln findest du im Abschnitt Cache-Laufzeit.
Setze bei früheren Modellen prompt_cache_retention vorzugsweise auf "24h", um die Aufbewahrung zu verlängern, sofern dein Modell und deine Anforderungen an die Datenaufbewahrung das zulassen. Die unterstützten Einstellungen und Standardwerte findest du im Abschnitt Cache-Laufzeit.
Wenn viele Anfragen dieselben Entwickleranweisungen und Tooldefinitionen verwenden, das gemeinsame Präfix aber die Mindestlänge für das Caching des Modells nicht erreicht, kannst du es kürzen oder mit nützlichen, stabilen Anweisungen, Beispielen oder Referenzmaterial erweitern. Prüfe anhand der tatsächlichen Kosten, ob die Wiederverwendung die zusätzlichen Eingabetoken und etwaige Schreibgebühren ausgleicht. Stelle außerdem sicher, dass die Evaluationsergebnisse und das Verhalten stabil bleiben.
Das Diagramm zeigt, wann ein kurzes Präfix ohne Caching mehr kostet als ein Präfix, das du auf die Mindestlänge für das Caching erweiterst. Die Berechnung verwendet den Schreibpreis für 30 Minuten Laufzeit bei Modellen ab GPT-5.6.
Prompt length and input cost
0
500
1,000
1,500
2,000
Reusable prefix length (tokens)
Für den reinen Kostenvergleich bezeichnet M die Mindestlänge für das Caching, L<M die ursprüngliche Präfixlänge, r den Preisfaktor für Cache-Lesezugriffe, w den Preisfaktor für Cache-Schreibzugriffe und N die Gesamtzahl der Anfragen. Angenommen, das erweiterte Präfix umfasst genau M Token, wird einmal geschrieben und bei jeder weiteren Anfrage vollständig wiederverwendet. Gemessen am Preis eines regulären Eingabetokens kostet das ursprüngliche Präfix insgesamt N×L, das erweiterte Präfix dagegen M[w+(N−1)r]. Bei folgender ursprünglicher Länge sind beide Varianten gleich teuer:
Lbreak-even=M(r+Nw−r)
Erweitere das Präfix, wenn L>Lbreak-even gilt. Bei L<Lbreak-even ist das kürzere Präfix günstiger. Bei Gleichheit sind die Kosten identisch. Die kleinste ganzzahlige Tokenanzahl, ab der sich eine Erweiterung lohnt, beträgt ⌊Lbreak-even⌋+1. Umgekehrt entfällt das Caching, wenn du ein geeignetes Präfix auf weniger als M Token kürzt. Unter denselben Annahmen muss die Länge des kürzeren Präfixes ohne Caching unter Lbreak-even liegen, damit es weniger kostet als das Caching von M Token. Es gibt keine allgemeingültige Prompt-Länge, bei der die Kosten am höchsten sind. Der Schwellenwert hängt von der Häufigkeit der Wiederverwendung und den Preisen ab.
Beim üblichen Cache-Lesepreis und bei Schreibzugriffen mit 30 Minuten Laufzeit ergibt sich für M=1,024, r=0.1 und w=1.25 ein Schwellenwert von 102.4+N1,177.6 Token. Bei insgesamt 10 Anfragen ist es günstiger, ein ursprüngliches Präfix von mindestens 221 Token auf 1.024 Token zu erweitern. Je häufiger du das Präfix wiederverwendest, desto näher liegt der Schwellenwert bei 102,4 Token. Bei einem Präfix von 103 Token lohnt sich die Erweiterung ab insgesamt 1.963 Anfragen. Bei höchstens 102 Token lohnt sie sich unter diesen Annahmen nie. Der Vergleich berücksichtigt weder die Leistung noch Ausgabetoken oder unveränderte Anfragekosten. Zusätzliche Anfragen ohne Cache-Treffer, weitere Schreibzugriffe oder andere Modellpreise ändern das Ergebnis.
Miss die tatsächliche Cache-Leistung. Erfasse usage.input_tokens_details.cached_tokens, usage.input_tokens_details.cache_write_tokens, die Anzahl der geschriebenen Token je Laufzeit, die Anzahl der Eingabetoken, die Latenz und die tatsächlichen Kosten. Für die tokenbezogene Cache-Trefferquote teilst du die Gesamtzahl der Token aus dem Cache durch die Gesamtzahl der Eingabetoken. Summiere beide Werte jeweils für dieselbe Person, denselben Workspace, denselben Tag oder eine andere für dich sinnvolle Gruppe.
Berechne die Eingabekosten. Verwende die Tokenanzahlen aus response.usage und die Preise pro Million Token des Modells.
Nutze das Dashboard für Prompt-Caching. Im Dashboard für Prompt-Caching kannst du die Cache-Trefferquoten verfolgen.
Bei Modellen der Responses API, die prompt_cache_options unterstützen, schlüsselt input_tokens_details.cache_write_tokens_details die geschriebenen Token nach Laufzeit in ttl_30m_tokens und ttl_12h_tokens auf. Diese beiden Mengen überschneiden sich nicht. Ihre Summe entspricht cache_write_tokens. Die API gibt beide Felder zurück, auch wenn eines den Wert null hat. cached_tokens zählt die als Lesezugriffe abgerechneten Token. Als Schreibzugriffe abgerechnete Token sind ausgenommen, auch bei einer Verlängerung von 30 Minuten auf 12 Stunden.
Nutzungsfelder für Eingabetoken bei Schreibzugriffen mit beiden Laufzeiten
In diesem Beispiel entfallen 1.000 Eingabetoken auf reguläre Eingaben: 12000 - 4000 - 7000. Für die Eingabekosten multiplizierst du die regulären Eingabetoken mit dem Eingabepreis des Modells, cached_tokens mit dem Preis für Eingaben aus dem Cache, ttl_30m_tokens mit dem 1,25-Fachen des Eingabepreises und ttl_12h_tokens mit dem 2,5-Fachen des Eingabepreises. Addiere die Beträge. Wenn du Preise pro Million Token verwendest, teile die Summe durch 1.000.000. Addiere cache_write_tokens nicht noch einmal, nachdem du die beiden Teilmengen berücksichtigt hast.
Bei einem regulären Eingabepreis von 1 USD pro Million Token und einem Preis von 0,10 USD pro Million Token aus dem Cache ergeben sich in diesem Beispiel Eingabekosten von (1000 + 4000 × 0.1 + 3000 × 1.25 + 4000 × 2.5) / 1000000 = $0.01515. Verwende die tatsächlichen Preise deines Modells, einschließlich des Preises für Eingaben aus dem Cache.
Die folgende Hilfsfunktion verwendet für alle Schreibzugriffe denselben Preisfaktor. Verwende 1.25, wenn alle Schreibzugriffe eine Laufzeit von 30 Minuten haben, oder 2.5, wenn alle eine Laufzeit von 12 Stunden haben. Berechne bei Anfragen mit beiden Laufzeiten die Kosten je Laufzeit wie oben beschrieben separat.
Eingabekosten bei einheitlichem Cache-Schreibpreis berechnen
Wenn du prompt_cache_key verwendest, behalte die vorhandenen Werte bei, damit du die Cache-Nutzung weiterhin getrennt nach Kundenkonto oder Person erfassen kannst.
Ersetze prompt_cache_retention durch prompt_cache_options.ttl.
Falls der standardmäßig gesetzte Haltepunkt Inhalte einschließt, die sich von Anfrage zu Anfrage ändern, füge nach dem stabilen Präfix einen expliziten Haltepunkt hinzu.
Verwende prompt_cache_options.mode: "explicit", wenn es sich nicht lohnt, nachfolgende Inhalte in den Cache zu schreiben.
Die folgenden Beispiele gelten für Modelle ab GPT-5.6.
Ein LLM prüft in einem einzigen Schritt, ob ein abgeschlossenes Gespräch mit einem Chatbot darauf hindeutet, dass die Person nach dem Gespräch zufrieden ist. Jede Anfrage bewertet ein anderes Gespräch anhand desselben Bewertungsrasters und derselben Few-Shot-Beispiele mit vorgegebenen Bewertungen.
Präfix beibehalten: Das feste Bewertungsraster und die Beispiele stehen am Anfang. Zusammen liegen sie bewusst knapp über der Mindestlänge für das Caching des Modells. Das Material hilft, die Bewertung durch das LLM zu kalibrieren. Das zu bewertende Gespräch steht am Ende.
Caching-Modus und Haltepunkt: Der rein explizite Modus ist aktiviert. Der Haltepunkt liegt hinter dem festen Bewertungsraster und den Beispielen. Das zu bewertende Gespräch mit dem Chatbot folgt erst danach und wird nicht in den Cache geschrieben. So entfällt die Schreibgebühr für Inhalte, die wahrscheinlich nicht erneut gebraucht werden.
Eine Implementierung nach diesem Muster erreichte eine tokenbezogene Cache-Trefferquote von rund 70 %. Das ist ein Beispiel für ein mögliches Ergebnis. Die maximal erreichbare Trefferquote hängt von deinem Kontext und davon ab, wie die Anwendung genutzt wird.
Anfrage an die Responses API für eine Bewertung in einem Schritt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22{"model": "gpt-6.1-sol","reasoning": { "effort": "medium", "context": "all_turns" },"text": { "verbosity": "low" },"prompt_cache_options": { "mode": "explicit" },"input": [ {"role": "developer","content": [ {"type": "input_text","text": "Judge whether the completed interaction provides evidence that the user is satisfied. Return true or false. Full grading rubric and labeled few-shot examples...","prompt_cache_breakpoint": { "mode": "explicit" } } ] }, {"role": "user","content": "Completed interaction to evaluate..." } ]}
Ein Agent arbeitet über mehrere Gesprächsschritte hinweg mit langen, gemeinsamen Entwickleranweisungen und ruft häufig Tools auf. Typischerweise führen Personen mehrere Sitzungen mit dem Agenten gleichzeitig und forken ihre Threads häufig.
Präfix beibehalten: Bei jedem Schritt kommen neue Nachrichten, Toolaufrufe und Ergebnisse hinzu. Der frühere Kontext bleibt unverändert, sodass das wiederverwendbare Präfix mit der Zeit wächst.
Optionaler Schlüssel für das Prompt-Caching: Das Beispiel verwendet agent_123_v1:user_456, um die Cache-Nutzung für das Nutzerkonto 456 getrennt zu erfassen. Dadurch lassen sich die Nutzung von Token aus dem Cache und deren Abrechnung leichter erklären. Das hilft auch zu verhindern, dass sich anhand von Cache-Treffern auf Inhalte anderer Personen schließen lässt. Der Schlüssel bleibt für alle Sitzungen und Forks dieses Kontos mit dem Agenten gleich. Lass ihn weg, wenn deine Anwendung diese Trennung nicht benötigt.
Impliziter Caching-Modus: Implizites Caching ist aktiviert. Dadurch liegt ein Haltepunkt am Ende der letzten zulässigen Nutzer- oder Toolnachricht.
Explizite Haltepunkte: Nach jedem Toolergebnis wird ein Haltepunkt gesetzt. So bleiben frühere wiederverwendbare Präfixe erhalten und der Cache lässt sich beim Forken effizienter nutzen.
Eine Implementierung nach diesem Muster erreichte eine tokenbezogene Cache-Trefferquote von über 90 %. Das ist ein Beispiel für ein mögliches Ergebnis. Die maximal erreichbare Trefferquote hängt von deinem Kontext und davon ab, wie die Anwendung genutzt wird.
Anfrage an die Responses API für einen Agenten mit mehreren Gesprächsschritten
Das fällt besonders beim Umstieg von früheren Modellen auf GPT-5.6 oder neuer auf, weil sich das implizite Caching anders verhält. Wenn Anfragen ein langes gemeinsames Präfix, aber unterschiedliche Suffixe haben, reicht es nicht, die erste vollständige Anfrage ausschließlich implizit im Cache zu speichern. Das kürzere gemeinsame Präfix lässt sich dadurch noch nicht wiederverwenden.
Angenommen, jede Anfrage enthält zuerst eine statische Entwicklernachricht und danach eine dynamische Nutzernachricht. Die Anfrage schreibt das Präfix einschließlich der dynamischen Inhalte in den Cache. Ändern sich diese Inhalte bei der nächsten Anfrage, stimmt das längere gespeicherte Präfix nicht mehr überein. Hinter dem statischen Inhalt gibt es keinen separaten Haltepunkt.
Setze deshalb in beiden Anfragen einen expliziten Haltepunkt hinter dem statischen Inhalt. Die erste Anfrage schreibt das wiederverwendbare Präfix in den Cache. Die nächste kann es nutzen, auch wenn sich der dynamische Inhalt ändert. Das Beispiel verwendet den rein expliziten Modus, damit der dynamische Inhalt nicht in den Cache geschrieben wird.
Angenommen, Anfrage 1 verwendet den impliziten Modus und speichert ein Präfix bis zum Ende einer Nutzernachricht. Die Folgeanfrage 2 behält dieses Präfix bei, wechselt aber zu prompt_cache_options.mode: "explicit". Wie unter So findet OpenAI passende Präfixe beschrieben, prüft Anfrage 2 nur explizite Haltepunkte in der eigenen Eingabe. Sie verwendet das implizit gespeicherte Präfix aus Anfrage 1 deshalb nur dann wieder, wenn einer ihrer expliziten Haltepunkte genau am Ende dieses Präfixes liegt.
▼ = breakpoint- Request 1: implicit mode [Developer message][User message] ▼- Request 2: explicit-only mode. Does not hit cache. [Developer message][User message][Follow-up] ▼
Um das implizit gespeicherte Präfix aus Anfrage 1 wiederzuverwenden, setze in Anfrage 2 einen expliziten Haltepunkt an der entsprechenden Inhaltsblockgrenze. Alternativ kannst du den impliziten Modus aktiviert lassen, damit OpenAI das Ende der früheren zulässigen Nachricht bei der Suche weiterhin berücksichtigt.
Selbst wenn beide Anfragen den impliziten Modus verwenden, reicht es nicht immer aus, dieselben Anfangstoken beizubehalten. Angenommen, Anfrage 1 endet mit einer Nutzernachricht mit dem Inhalt Content A. Die Folgeanfrage 2 erweitert dieselbe Nachricht auf Content A + Content B. Die frühere Grenze hinter Content A liegt jetzt innerhalb einer Nachricht statt an deren Ende. Wie unter So findet OpenAI passende Präfixe beschrieben, verwendet Anfrage 2 das dort gespeicherte Präfix ohne expliziten Haltepunkt an dieser Stelle nicht wieder.
▼ = breakpoint- Request 1: implicit mode [Developer message][User message: Content A] ▼- Request 2: implicit mode. Cannot reuse the prefix through Content A. [Developer message][User message: Content A + Content B] ▼
Wenn es die Gesprächsstruktur zulässt, behalte die ursprüngliche Nachricht bei und hänge eine neue an. Andernfalls platziere den wiederverwendbaren Text in einem eigenen Inhaltsblock und setze in beiden Anfragen dahinter einen expliziten Haltepunkt.
Im impliziten Modus berücksichtigt die Cache-Suche das Ende von Entwicklernachrichten nach dem anfänglichen Block unmittelbar aufeinanderfolgender Entwicklernachrichten nicht automatisch. Setze am Ende einer wiederverwendbaren Entwicklernachricht einen expliziten Haltepunkt und behalte ihn in späteren Anfragen bei. So kann OpenAI dort nach einem passenden Präfix im Cache suchen.
Ein Präfix, das für das Caching bei einem Modell ausreicht, kann für ein anderes zu kurz sein. Sieh dir den Modellvergleich an und miss die Länge des wiederverwendbaren Präfixes mit dem Modell und den Einstellungen, die du tatsächlich verwendest. Wiederhole die Prüfung bei einem Modellwechsel, statt den bisherigen Schwellenwert vorauszusetzen.
Bei der Kontextverdichtung wird früherer Gesprächskontext durch eine kürzere Darstellung ersetzt. Dadurch kann sich das Präfix ändern. Die erste Anfrage nach der Verdichtung kann dann weniger aus dem bisherigen Cache wiederverwenden, obwohl das Gespräch inhaltlich dasselbe bleibt.
Halte wiederverwendbare Anweisungen und Referenzmaterial nach Möglichkeit stabil und nutze den verdichteten Kontext als Grundlage für die weiteren Gesprächsschritte. Vergleiche die gesamten Eingabekosten vor und nach der Kontextverdichtung. Weniger Eingabetoken können die Kosten senken, selbst wenn die Cache-Trefferquote sinkt.
Häufig gestellte Fragen
Nein. Prompt-Caching ändert nicht, wie das Modell Ausgabetoken erzeugt. Das Modell erzeugt mit dem gespeicherten Präfix eine neue Antwort. Identische Anfragen liefern daher nicht zwangsläufig identische Ausgaben.
Nein. Derzeit kannst du den Cache nicht manuell leeren. Wann Einträge ablaufen, richtet sich nach der Cache-Laufzeit des Modells und den Aufbewahrungseinstellungen.
Ja. Eingabetoken aus dem Cache zählen weiterhin für das Limit an Token pro Minute. Prompt-Caching ändert nichts an der Berechnung der Ratenlimits.
Beim Prompt-Caching werden Key-Value-Tensoren (KV-Tensoren) anstelle des ursprünglichen Prompt-Texts gespeichert. Diese Tensoren können bis zu 24 Stunden als verschlüsselter Anwendungszustand im lokalen GPU-Speicher verbleiben. Angaben zu den modellspezifischen Laufzeiten und ihrer Verlängerung findest du im Abschnitt Cache-Laufzeit.
Jede Organisation hat eigene Caches. Eine Wiederverwendung über die Grenzen der jeweiligen Verarbeitungsregion hinweg ist nicht möglich. Wie die einzelnen API-Funktionen mit Daten umgehen und welche für ZDR infrage kommen, erfährst du unter Deine Daten.