Cached Contents

Verwalten Sie explizite Kontext-Caches (cachedContents) über das Gemini-native Protokoll: Cachen Sie aktiv einen großen Kontext als Objekt und referenzieren Sie es über Anfragen hinweg, für deterministischere Treffer und niedrigere Kosten. OfoxAI ist mit dem Google GenAI SDK kompatibel.

Anwendungsfälle, den Unterschied zum impliziten Caching und Best Practices finden Sie im Leitfaden zum Gemini Expliziten Caching. Diese Seite ist die API-Referenz auf Endpunkt-Ebene.

Endpunkte


POST   https://api.ofox.ai/gemini/v1beta/cachedContents              # Erstellen
GET    https://api.ofox.ai/gemini/v1beta/cachedContents/{id}         # Abfragen
DELETE https://api.ofox.ai/gemini/v1beta/cachedContents/{id}         # Löschen

Um einen Cache für die Inhaltsgenerierung zu referenzieren, verwenden Sie den Standard-generateContent-Endpunkt mit einem cachedContent-Feld im Body:


POST   https://api.ofox.ai/gemini/v1beta/models/{model}:generateContent

Authentifizierung

Verwenden Sie den x-goog-api-key-Header:


x-goog-api-key: <Ihr OFOXAI_API_KEY>

Ressourcenfelder

Wichtige Felder der CachedContent-Ressource:

Feld	Typ	Beschreibung
`name`	string (nur Ausgabe)	Cache-Handle, z. B. `cachedContents/{id}`, bei der Erstellung zurückgegeben
`model`	string (erforderlich, unveränderlich)	Modell, an das der Cache gebunden ist, z. B. `models/gemini-3.1-pro-preview`
`contents`	array	Zu cachender Inhalt (gleiche Struktur wie `contents` von generateContent)
`systemInstruction`	object	Zu cachende System-Anweisung (optional)
`tools`	array	Zu cachende Tool-Definitionen (optional)
`ttl`	string	Lebensdauer, Sekunden-String (z. B. `"600s"`); schließt sich mit `expireTime` gegenseitig aus
`expireTime`	string	Ablaufzeitpunkt (RFC 3339); schließt sich mit `ttl` gegenseitig aus
`displayName`	string (unveränderlich)	Benutzerdefinierter Name (optional)
`usageMetadata.totalTokenCount`	integer	Anzahl der gecachten Tokens (für die Abrechnung verwendet)

Unterstützter TTL-Bereich: minimal / Standard 600s (10 Minuten), maximal 3600s (1 Stunde).

Cache erstellen

Python

create.py


from google import genai
from google.genai import types
 
client = genai.Client(
    api_key="<Ihr OFOXAI_API_KEY>",
    http_options={"api_version": "v1beta", "base_url": "https://api.ofox.ai/gemini"},
)
 
cache = client.caches.create(
    model="google/gemini-3.1-pro-preview",
    config=types.CreateCachedContentConfig(
        contents=[open("knowledge_base.txt").read()],
        system_instruction="Sie antworten ausschließlich auf Basis des bereitgestellten Dokuments.",
        ttl="600s",
        display_name="kb-v1",
    ),
)
 
print(cache.name)                          # cachedContents/xxxxxxxx
print(cache.usage_metadata.total_token_count)

TypeScript

create.ts


import { GoogleGenAI } from '@google/genai'
import fs from 'node:fs'
 
const ai = new GoogleGenAI({
  apiKey: '<Ihr OFOXAI_API_KEY>',
  httpOptions: { apiVersion: 'v1beta', baseUrl: 'https://api.ofox.ai/gemini' },
})
 
const cache = await ai.caches.create({
  model: 'google/gemini-3.1-pro-preview',
  config: {
    contents: [fs.readFileSync('knowledge_base.txt', 'utf-8')],
    systemInstruction: 'Sie antworten ausschließlich auf Basis des bereitgestellten Dokuments.',
    ttl: '600s',
    displayName: 'kb-v1',
  },
})
 
console.log(cache.name) // cachedContents/xxxxxxxx
console.log(cache.usageMetadata?.totalTokenCount)

cURL

Terminal


curl "https://api.ofox.ai/gemini/v1beta/cachedContents" \
  -H "x-goog-api-key: $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3.1-pro-preview",
    "contents": [
      { "role": "user", "parts": [{ "text": "<zu cachender großer Kontext>" }] }
    ],
    "ttl": "600s"
  }'

Antwort


{
  "name": "cachedContents/xxxxxxxx",
  "model": "google/gemini-3.1-pro-preview",
  "createTime": "2026-06-26T08:00:00Z",
  "updateTime": "2026-06-26T08:00:00Z",
  "expireTime": "2026-06-26T08:10:00Z",
  "displayName": "kb-v1",
  "usageMetadata": {
    "totalTokenCount": 14407
  }
}

Abfragen / Löschen

Abfragen und Löschen erfordern kein model; OfoxAI lokalisiert den Upstream anhand des Cache-Handles.

Python

manage.py


# Einzeln abfragen
info = client.caches.get(name=cache.name)
print(info.expire_time)
 
# Löschen
client.caches.delete(name=cache.name)

TypeScript

manage.ts


// Einzeln abfragen
const info = await ai.caches.get({ name: cache.name })
console.log(info.expireTime)
 
// Löschen
await ai.caches.delete({ name: cache.name })

cURL

Terminal


# Einzeln abfragen
curl "https://api.ofox.ai/gemini/v1beta/cachedContents/xxxxxxxx" \
  -H "x-goog-api-key: $OFOX_API_KEY"
 
# Löschen
curl -X DELETE "https://api.ofox.ai/gemini/v1beta/cachedContents/xxxxxxxx" \
  -H "x-goog-api-key: $OFOX_API_KEY"

Cache zur Generierung referenzieren

Fügen Sie dem generateContent-Body ein cachedContent-Feld hinzu, um den Cache zu referenzieren; contents enthält nur die neue Frage für diesen Schritt:

Python

use.py


response = client.models.generate_content(
    model="google/gemini-3.1-pro-preview",
    contents="Fassen Sie auf Basis des obigen Dokuments drei Kernpunkte zusammen",
    config=types.GenerateContentConfig(cached_content=cache.name),
)
 
print(response.text)
print(response.usage_metadata.cached_content_token_count)  # Anzahl der getroffenen Cache-Tokens

TypeScript

use.ts


const response = await ai.models.generateContent({
  model: 'google/gemini-3.1-pro-preview',
  contents: 'Fassen Sie auf Basis des obigen Dokuments drei Kernpunkte zusammen',
  config: { cachedContent: cache.name },
})
 
console.log(response.text)
console.log(response.usageMetadata?.cachedContentTokenCount) // Anzahl der getroffenen Cache-Tokens

cURL

Terminal


curl "https://api.ofox.ai/gemini/v1beta/models/google/gemini-3.1-pro-preview:generateContent" \
  -H "x-goog-api-key: $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cachedContent": "cachedContents/xxxxxxxx",
    "contents": [
      { "role": "user", "parts": [{ "text": "Fassen Sie auf Basis des obigen Dokuments drei Kernpunkte zusammen" }] }
    ]
  }'

Bei einem Treffer zeigt usageMetadata.cachedContentTokenCount in der Antwort, wie viele Tokens aus dem Cache stammen.

Abrechnung

Phase	Formel
Cache erstellen	`totalTokenCount × cache_write Tarif`
Referenz-Treffer	`cachedContentTokenCount × cache_read Tarif` (etwa 0,10x des Standard-Eingabepreises)
Neue Inhalte pro Referenz	Neuer Prompt / neue Ausgabe pro Schritt zum Standardtarif

Die cache_write / cache_read-Einzelpreise der einzelnen Modelle finden Sie im Modellkatalog .

OfoxAI verteilt die Last über mehrere GCP-Projekte, und explizite Caches sind regionsgebunden (region-scoped). OfoxAI sperrt Referenzen automatisch anhand des Cache-Handles hart zurück auf den Upstream, der den Cache erstellt hat, mit null Drift bei Referenzen; ein Cache-Handle kann nur von dem API Key referenziert / abgefragt / gelöscht werden, der es erstellt hat (kontoübergreifender Zugriff gibt 403 zurück). Details unter Leitfaden zum Expliziten Caching · Deterministisches Routing.

Cached Contents

Endpunkte

Authentifizierung

Ressourcenfelder

Cache erstellen

Python

TypeScript

cURL

Antwort

Abfragen / Löschen

Python

TypeScript

cURL

Cache zur Generierung referenzieren

Python

TypeScript

cURL

Abrechnung

Verwandte Dokumente