Cached Contents

Управляйте явным кэшем контекста (cachedContents) через нативный протокол Gemini: самостоятельно кэшируйте большой контекст как объект и ссылайтесь на него между запросами для детерминированных попаданий и меньших затрат. OfoxAI совместим с Google GenAI SDK.

Сценарии применения, отличие от неявного кэширования и лучшие практики см. в руководстве по явному кэшированию Gemini. Эта страница — справочник по API на уровне эндпоинтов.

Эндпоинты


POST   https://api.ofox.ai/gemini/v1beta/cachedContents              # Создание
GET    https://api.ofox.ai/gemini/v1beta/cachedContents/{id}         # Запрос
DELETE https://api.ofox.ai/gemini/v1beta/cachedContents/{id}         # Удаление

Для ссылки на кэш при генерации контента используется стандартный эндпоинт generateContent с полем cachedContent в теле запроса:


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

Аутентификация

Используйте заголовок x-goog-api-key:


x-goog-api-key: <Ваш OFOXAI_API_KEY>

Поля ресурса

Основные поля ресурса CachedContent:

Поле	Тип	Описание
`name`	string (только чтение)	Дескриптор кэша вида `cachedContents/{id}`, возвращается после создания
`model`	string (обязательное, неизменяемое)	Модель, к которой привязан кэш, например `models/gemini-3.1-pro-preview`
`contents`	array	Содержимое для кэширования (та же структура, что у `contents` в generateContent)
`systemInstruction`	object	Системная инструкция для кэширования (необязательно)
`tools`	array	Определения инструментов для кэширования (необязательно)
`ttl`	string	Время жизни, строка с числом секунд (например, `"600s"`); взаимоисключающее с `expireTime`
`expireTime`	string	Момент истечения (RFC 3339); взаимоисключающее с `ttl`
`displayName`	string (неизменяемое)	Пользовательское имя (необязательно)
`usageMetadata.totalTokenCount`	integer	Число кэшированных токенов (используется для тарификации)

Поддерживаемый диапазон TTL: минимум / по умолчанию 600s (10 минут), максимум 3600s (1 час).

Создание кэша

Python

create.py


from google import genai
from google.genai import types
 
client = genai.Client(
    api_key="<Ваш 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="Ты — ассистент, который отвечает строго на основе предоставленного документа.",
        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: '<Ваш 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: 'Ты — ассистент, который отвечает строго на основе предоставленного документа.',
    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": "<большой контекст для кэширования>" }] }
    ],
    "ttl": "600s"
  }'

Ответ


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

Запрос / удаление

Запрос и удаление не требуют передачи model — OfoxAI находит upstream по дескриптору кэша.

Python

manage.py


# Запрос одной записи
info = client.caches.get(name=cache.name)
print(info.expire_time)
 
# Удаление
client.caches.delete(name=cache.name)

TypeScript

manage.ts


// Запрос одной записи
const info = await ai.caches.get({ name: cache.name })
console.log(info.expireTime)
 
// Удаление
await ai.caches.delete({ name: cache.name })

cURL

Terminal


# Запрос одной записи
curl "https://api.ofox.ai/gemini/v1beta/cachedContents/xxxxxxxx" \
  -H "x-goog-api-key: $OFOX_API_KEY"
 
# Удаление
curl -X DELETE "https://api.ofox.ai/gemini/v1beta/cachedContents/xxxxxxxx" \
  -H "x-goog-api-key: $OFOX_API_KEY"

Генерация со ссылкой на кэш

Добавьте поле cachedContent в тело generateContent, чтобы сослаться на кэш; в contents помещается только новый вопрос этого хода:

Python

use.py


response = client.models.generate_content(
    model="google/gemini-3.1-pro-preview",
    contents="На основе документа выше сформулируй три ключевых тезиса",
    config=types.GenerateContentConfig(cached_content=cache.name),
)
 
print(response.text)
print(response.usage_metadata.cached_content_token_count)  # число попавших в кэш токенов

TypeScript

use.ts


const response = await ai.models.generateContent({
  model: 'google/gemini-3.1-pro-preview',
  contents: 'На основе документа выше сформулируй три ключевых тезиса',
  config: { cachedContent: cache.name },
})
 
console.log(response.text)
console.log(response.usageMetadata?.cachedContentTokenCount) // число попавших в кэш токенов

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": "На основе документа выше сформулируй три ключевых тезиса" }] }
    ]
  }'

При попадании поле ответа usageMetadata.cachedContentTokenCount показывает число токенов, взятых из кэша.

Тарификация

Этап	Формула
Создание кэша	`totalTokenCount × цена cache_write`
Попадание по ссылке	`cachedContentTokenCount × цена cache_read` (примерно 0.10x от стандартной цены ввода)
Новое содержимое при ссылке	Новые prompt / вывод этого хода по стандартной цене

Цены cache_write / cache_read для каждой модели см. в каталоге моделей .

OfoxAI балансирует нагрузку между несколькими проектами GCP, а явный кэш привязан к региону (region-scoped). OfoxAI автоматически по дескриптору кэша жёстко фиксирует ссылки обратно на upstream, где был создан кэш, с нулевым дрейфом; на дескриптор кэша можно ссылаться / запрашивать / удалять только тем API Key, который его создал (межаккаунтный доступ возвращает 403). Подробнее см. руководство по явному кэшированию · Детерминированная маршрутизация.

Cached Contents

Эндпоинты

Аутентификация

Поля ресурса

Создание кэша

Python

TypeScript

cURL

Ответ

Запрос / удаление

Python

TypeScript

cURL

Генерация со ссылкой на кэш

Python

TypeScript

cURL

Тарификация

Связанные документы