Cached Contents

Administre cachés de contexto explícitos (cachedContents) a través del protocolo nativo de Gemini: cachee de forma activa un gran contexto como un objeto y referéncielo entre solicitudes para obtener aciertos deterministas y menor costo. OfoxAI es compatible con el Google GenAI SDK.

Para los escenarios de uso, la diferencia con el caché implícito y las mejores prácticas, consulte la Guía de caché explícito de Gemini. Esta página es la referencia de la API a nivel de endpoint.

Endpoints


POST   https://api.ofox.ai/gemini/v1beta/cachedContents              # Crear
GET    https://api.ofox.ai/gemini/v1beta/cachedContents/{id}         # Consultar
DELETE https://api.ofox.ai/gemini/v1beta/cachedContents/{id}         # Eliminar

Para referenciar un caché en la generación de contenido, use el endpoint estándar generateContent con un campo cachedContent en el cuerpo:


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

Autenticación

Use el header x-goog-api-key:


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

Campos del recurso

Campos principales del recurso CachedContent:

Campo	Tipo	Descripción
`name`	string (solo lectura)	Identificador del caché, con la forma `cachedContents/{id}`, devuelto al crear
`model`	string (obligatorio, inmutable)	Modelo al que está vinculado el caché, p. ej. `models/gemini-3.1-pro-preview`
`contents`	array	Contenido a cachear (misma estructura que el `contents` de generateContent)
`systemInstruction`	object	Instrucción de sistema a cachear (opcional)
`tools`	array	Definiciones de herramientas a cachear (opcional)
`ttl`	string	Tiempo de vida, una cadena de segundos (p. ej. `"600s"`); mutuamente excluyente con `expireTime`
`expireTime`	string	Marca de tiempo de expiración (RFC 3339); mutuamente excluyente con `ttl`
`displayName`	string (inmutable)	Nombre personalizado (opcional)
`usageMetadata.totalTokenCount`	integer	Número de tokens cacheados (usado para la facturación)

Rango de TTL soportado: mínimo / por defecto 600s (10 minutos), máximo 3600s (1 hora).

Crear un caché

Python

create.py


from google import genai
from google.genai import types
 
client = genai.Client(
    api_key="<su 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="Respondes basándote estrictamente en el documento proporcionado.",
        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: '<su 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: 'Respondes basándote estrictamente en el documento proporcionado.',
    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": "<gran contexto a cachear>" }] }
    ],
    "ttl": "600s"
  }'

Respuesta


{
  "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
  }
}

Consultar / Eliminar

Consultar y eliminar no requieren model; OfoxAI localiza el upstream a partir del identificador del caché.

Python

manage.py


# Consultar uno
info = client.caches.get(name=cache.name)
print(info.expire_time)
 
# Eliminar
client.caches.delete(name=cache.name)

TypeScript

manage.ts


// Consultar uno
const info = await ai.caches.get({ name: cache.name })
console.log(info.expireTime)
 
// Eliminar
await ai.caches.delete({ name: cache.name })

cURL

Terminal


# Consultar uno
curl "https://api.ofox.ai/gemini/v1beta/cachedContents/xxxxxxxx" \
  -H "x-goog-api-key: $OFOX_API_KEY"
 
# Eliminar
curl -X DELETE "https://api.ofox.ai/gemini/v1beta/cachedContents/xxxxxxxx" \
  -H "x-goog-api-key: $OFOX_API_KEY"

Referenciar un caché para generar

Agregue un campo cachedContent al cuerpo de generateContent para referenciar el caché; contents solo lleva la nueva pregunta de este turno:

Python

use.py


response = client.models.generate_content(
    model="google/gemini-3.1-pro-preview",
    contents="Basándote en el documento anterior, resume tres puntos clave",
    config=types.GenerateContentConfig(cached_content=cache.name),
)
 
print(response.text)
print(response.usage_metadata.cached_content_token_count)  # tokens de caché acertados

TypeScript

use.ts


const response = await ai.models.generateContent({
  model: 'google/gemini-3.1-pro-preview',
  contents: 'Basándote en el documento anterior, resume tres puntos clave',
  config: { cachedContent: cache.name },
})
 
console.log(response.text)
console.log(response.usageMetadata?.cachedContentTokenCount) // tokens de caché acertados

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": "Basándote en el documento anterior, resume tres puntos clave" }] }
    ]
  }'

En un acierto, el usageMetadata.cachedContentTokenCount de la respuesta muestra cuántos tokens provienen del caché.

Facturación

Etapa	Fórmula
Crear caché	`totalTokenCount × tarifa cache_write`
Acierto por referencia	`cachedContentTokenCount × tarifa cache_read` (~0.10x del precio estándar de entrada)
Nuevo contenido por referencia	El nuevo prompt / salida del turno se cobra a tarifas estándar

Los precios unitarios cache_write / cache_read de cada modelo están en el catálogo de modelos .

OfoxAI balancea la carga entre múltiples proyectos de GCP, y los cachés explícitos son region-scoped (vinculados a la región). OfoxAI fija automáticamente de forma rígida las referencias de vuelta al upstream que creó el caché, con cero deriva; un identificador de caché solo puede ser referenciado / consultado / eliminado por la API Key que lo creó (el acceso entre cuentas devuelve 403). Consulte Guía de caché explícito · Enrutamiento determinista.

Cached Contents

Endpoints

Autenticación

Campos del recurso

Crear un caché

Python

TypeScript

cURL

Respuesta

Consultar / Eliminar

Python

TypeScript

cURL

Referenciar un caché para generar

Python

TypeScript

cURL

Facturación

Documentación relacionada