OpenAI-Kontextcache verwenden

Bei GPT-5.6 und neueren Modellen, die diese Funktion unterstützen, legt prompt_cache_options.ttl in einer Responses-API-Anfrage die Mindestlebensdauer des Caches auf 30 Minuten oder 12 Stunden fest. Die Beispiele verwenden gpt-6.1-terra.

Der 12-Stunden-Cache wird nur von /v1/responses unterstützt, nicht von /v1/chat/completions. Die TTL ist eine Mindestlebensdauer, kein Löschtermin und keine Garantie für einen Cache-Treffer bei jeder Anfrage.

API-Schlüssel festlegen

export API_KEY="YOUR_API_KEY"

Der lange Text in den Beispielen ist ein Platzhalter. Ersetzen Sie ihn durch den wiederzuverwendenden Inhalt. Das cachefähige Präfix muss mindestens 1.024 Tokens enthalten; der kurze Platzhalter allein löst keinen Cache-Schreibvorgang aus.

30-Minuten-Cache verwenden

Setzen Sie prompt_cache_options.ttl auf "30m". Ohne ttl gelten ebenfalls 30 Minuten. Ohne mode wird implizites Caching verwendet: Der vorgelagerte Dienst wählt den Cache-Haltepunkt automatisch.

curl "https://api.apimart.ai/v1/responses" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-6.1-terra",
  "prompt_cache_options": {
    "ttl": "30m"
  },
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Long reference material to reuse (at least 1024 tokens)... Summarize the key points."
        }
      ]
    }
  ]
}'

12-Stunden-Cache verwenden

Ändern Sie dasselbe Feld auf "12h". Die übrige Anfragestruktur bleibt gleich:

curl "https://api.apimart.ai/v1/responses" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-6.1-terra",
  "prompt_cache_options": {
    "ttl": "12h"
  },
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Long reference material to reuse (at least 1024 tokens)... Summarize the key points."
        }
      ]
    }
  ]
}'

Ein festes Präfix für verschiedene Fragen wiederverwenden

Um ein langes Dokument wiederzuverwenden und nur die letzte Frage zu ändern, setzen Sie mode auf "explicit" und ergänzen Sie prompt_cache_breakpoint im input_text-Block am Ende des festen Inhalts. Dieses Beispiel verwendet 12 Stunden. Für 30 Minuten ändern Sie die TTL der Anfrage auf "30m".

Mit mode: "explicit" ohne Haltepunkt wird der Cache weder gelesen noch beschrieben. Der folgende Haltepunkt hat keine eigene TTL und übernimmt daher prompt_cache_options.ttl aus der Anfrage.

curl "https://api.apimart.ai/v1/responses" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-6.1-terra",
  "prompt_cache_options": {
    "ttl": "12h",
    "mode": "explicit"
  },
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Long reference material to reuse (at least 1024 tokens)...",
          "prompt_cache_breakpoint": {
            "mode": "explicit"
          }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Summarize the three main points in the reference material."
        }
      ]
    }
  ]
}'

Senden Sie bei Folgeanfragen dasselbe Modell, Präfix und denselben Haltepunkt. Ändern Sie nur die letzte Benutzernachricht. Inhalt, Reihenfolge und kontextrelevante Einstellungen müssen gleich bleiben. Eine Cache-ID müssen Sie weder erstellen noch übergeben.

Cache-Nutzung prüfen

Prüfen Sie usage.input_tokens_details in der Antwort:

cached_tokens: In dieser Anfrage aus dem Cache gelesene Tokens. Ein Wert über 0 zeigt einen Cache-Lesevorgang an.
cache_write_tokens: Gesamtzahl der in dieser Anfrage in den Cache geschriebenen Tokens.
cache_write_tokens_details.ttl_30m_tokens: In dieser Anfrage mit einer TTL von 30 Minuten geschriebene Tokens.
cache_write_tokens_details.ttl_12h_tokens: In dieser Anfrage mit einer TTL von 12 Stunden geschriebene Tokens.

Senden Sie nach dem ersten Schreibvorgang eine weitere Anfrage mit demselben stabilen Präfix und prüfen Sie cached_tokens. Bei einem zu kurzen oder geänderten Präfix oder einem Cache-Miss kann der Wert 0 sein.

Cache-Usage-Beispiel und Token-Zählung

Dieser Antwortauszug zeigt nur usage für ein OpenAI-Modell mit Cache-Unterstützung und Schreibvorgängen für beide TTLs. Die tatsächlichen Werte ergeben sich aus der Antwort.

{
  "usage": {
    "input_tokens": 12000,
    "input_tokens_details": {
      "cached_tokens": 4000,
      "cache_write_tokens": 7000,
      "cache_write_tokens_details": {
        "ttl_30m_tokens": 5000,
        "ttl_12h_tokens": 2000
      }
    },
    "output_tokens": 1000,
    "total_tokens": 13000
  }
}

Normale Eingabe-Tokens:

input_tokens - input_tokens_details.cached_tokens - input_tokens_details.cache_write_tokens

cache_write_tokens = ttl_30m_tokens + ttl_12h_tokens
total_tokens = input_tokens + output_tokens

Cache-Lese- und Schreibmengen sind bereits in input_tokens enthalten. Die beiden TTL-Mengen sind Teilmengen von cache_write_tokens. Addieren Sie nicht erneut Gesamtmenge und Teilmengen oder Cache-Mengen zur gesamten Eingabe. Hier beträgt die normale Eingabe 12000 - 4000 - 7000 = 1000, die Schreibmenge 5000 + 2000 = 7000 und die gesamte Token-Anzahl 12000 + 1000 = 13000. Details zum Verhalten finden Sie im offiziellen OpenAI-Leitfaden zum Prompt-Caching.

Übersicht

Modelle

Textserie

Bildserie

Videoserie

Audioserie

Moderationsserie

Upload-Verwaltung

Aufgabenverwaltung

Kontoverwaltung

OpenAI-Kontextcache verwenden

API-Schlüssel festlegen

30-Minuten-Cache verwenden

12-Stunden-Cache verwenden

Ein festes Präfix für verschiedene Fragen wiederverwenden

Cache-Nutzung prüfen

Cache-Usage-Beispiel und Token-Zählung

​API-Schlüssel festlegen

​30-Minuten-Cache verwenden

​12-Stunden-Cache verwenden

​Ein festes Präfix für verschiedene Fragen wiederverwenden

​Cache-Nutzung prüfen

​Cache-Usage-Beispiel und Token-Zählung

API-Schlüssel festlegen

30-Minuten-Cache verwenden

12-Stunden-Cache verwenden

Ein festes Präfix für verschiedene Fragen wiederverwenden

Cache-Nutzung prüfen

Cache-Usage-Beispiel und Token-Zählung