Cached Contents

Gerencie caches de contexto explícitos (cachedContents) via protocolo nativo do Gemini: armazene ativamente um grande contexto como um objeto e o referencie entre requisições para acertos determinísticos e menor custo. O OfoxAI é compatível com o Google GenAI SDK.

Para casos de uso, a diferença em relação ao cache implícito e boas práticas, veja o guia de Cache explícito do Gemini. Esta página é a referência da API no nível de endpoint.

Endpoints


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

Para referenciar um cache na geração de conteúdo, use o endpoint padrão generateContent com o campo cachedContent no corpo:


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

Autenticação

Use o header x-goog-api-key:


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

Campos do recurso

Principais campos do recurso CachedContent:

Campo	Tipo	Descrição
`name`	string (somente leitura)	Handle do cache, no formato `cachedContents/{id}`, retornado na criação
`model`	string (obrigatório, imutável)	Modelo ao qual o cache está vinculado, como `models/gemini-3.1-pro-preview`
`contents`	array	Conteúdo a armazenar em cache (mesma estrutura do `contents` do generateContent)
`systemInstruction`	object	Instrução de system a armazenar em cache (opcional)
`tools`	array	Definições de ferramentas a armazenar em cache (opcional)
`ttl`	string	Tempo de vida, string de segundos (como `"600s"`); mutuamente exclusivo com `expireTime`
`expireTime`	string	Momento de expiração (RFC 3339); mutuamente exclusivo com `ttl`
`displayName`	string (imutável)	Nome personalizado (opcional)
`usageMetadata.totalTokenCount`	integer	Número de tokens em cache (usado no faturamento)

Faixa de TTL suportada: mínimo / padrão 600s (10 minutos), máximo 3600s (1 hora).

Criar um cache

Python

create.py


from google import genai
from google.genai import types
 
client = genai.Client(
    api_key="<Sua 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="Você é um assistente que responde estritamente com base no documento fornecido.",
        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: '<Sua 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: 'Você é um assistente que responde estritamente com base no documento fornecido.',
    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": "<contexto grande a armazenar em cache>" }] }
    ],
    "ttl": "600s"
  }'

Resposta


{
  "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 / Excluir

Consultar e excluir não exigem passar model; o OfoxAI localiza o upstream pelo handle do cache.

Python

manage.py


# Consultar um item
info = client.caches.get(name=cache.name)
print(info.expire_time)
 
# Excluir
client.caches.delete(name=cache.name)

TypeScript

manage.ts


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

cURL

Terminal


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

Referenciar um cache para gerar

Adicione o campo cachedContent ao corpo do generateContent para referenciar o cache; contents carrega apenas a nova pergunta desta vez:

Python

use.py


response = client.models.generate_content(
    model="google/gemini-3.1-pro-preview",
    contents="Com base no documento acima, resuma três pontos principais",
    config=types.GenerateContentConfig(cached_content=cache.name),
)
 
print(response.text)
print(response.usage_metadata.cached_content_token_count)  # tokens de cache acertados

TypeScript

use.ts


const response = await ai.models.generateContent({
  model: 'google/gemini-3.1-pro-preview',
  contents: 'Com base no documento acima, resuma três pontos principais',
  config: { cachedContent: cache.name },
})
 
console.log(response.text)
console.log(response.usageMetadata?.cachedContentTokenCount) // tokens de cache 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": "Com base no documento acima, resuma três pontos principais" }] }
    ]
  }'

No acerto, o usageMetadata.cachedContentTokenCount da resposta mostra quantos tokens vieram do cache.

Faturamento

Etapa	Fórmula
Criar cache	`totalTokenCount × tarifa de cache_write`
Acerto na referência	`cachedContentTokenCount × tarifa de cache_read` (cerca de 0,10x do preço de entrada padrão)
Novo conteúdo por referência	Novo prompt / saída desta vez cobrado pelas tarifas padrão

Os preços unitários de cache_write / cache_read de cada modelo estão no catálogo de modelos .

O OfoxAI faz balanceamento de carga entre vários projetos GCP, e os caches explícitos são region-scoped (vinculados à região). O OfoxAI trava (hard-lock) automaticamente as referências de volta ao upstream que criou o cache, com zero drift; um handle de cache só pode ser referenciado / consultado / excluído pela API Key que o criou (acesso entre contas retorna 403). Veja o guia de Cache explícito · Roteamento determinístico.

Cached Contents

Endpoints

Autenticação

Campos do recurso

Criar um cache

Python

TypeScript

cURL

Resposta

Consultar / Excluir

Python

TypeScript

cURL

Referenciar um cache para gerar

Python

TypeScript

cURL

Faturamento

Documentos relacionados