Guía de uso de la caché de contexto de Gemini

En esta guía se explica cómo crear y reutilizar la caché de contexto de Gemini (Context Cache) mediante la API Chat Completions compatible con OpenAI o la API nativa de Gemini. Antes de empezar:

export API_KEY="TU_CLAVE_API"

Los ejemplos de esta guía usan gemini-3.6-flash. Para saber si otros modelos admiten Context Cache, consulta la descripción del modelo y la página de precios de la plataforma.

Casos de uso

Cuando varias solicitudes incluyen repetidamente el mismo bloque grande de contenido, puedes almacenar en caché un prefijo estable, por ejemplo:

Un system prompt muy largo
Una base de conocimientos fija o documentación de producto
Mensajes históricos estables de una conversación de varios turnos
Definiciones e instrucciones de herramientas que se reutilizan

Context Cache es adecuado para solicitudes en las que «el contenido inicial permanece igual y solo cambia la pregunta final».

Uso básico

Añade cache_control al bloque de contenido del último mensaje del prefijo estable:

{
  "type": "text",
  "text": "Este es el último fragmento de contenido del prefijo estable",
  "cache_control": {
    "type": "ephemeral",
    "ttl": "5m"
  }
}

TTL admitidos:

TTL	Significado
`5m`	Caché durante 5 minutos
`1h`	Caché durante 1 hora

Si omites ttl, se usa 5m de forma predeterminada.

Estructura de los mensajes

Se recomienda usar la siguiente estructura:

system
→ Texto largo estable o mensajes históricos
→ Límite del prefijo estable con cache_control
→ Pregunta actual del usuario (no se almacena en caché)

El mensaje que contiene cache_control y todos los mensajes anteriores forman el prefijo almacenado en caché. Después debe haber al menos un mensaje en tiempo real.

Ejemplo de solicitud compatible con OpenAI

curl "https://api.apimart.ai/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.6-flash",
    "stream": false,
    "messages": [
      {
        "role": "system",
        "content": "Responde estrictamente de acuerdo con el material de referencia proporcionado."
      },
      {
        "role": "user",
        "content": "Aquí se incluye el material de referencia extenso que se reutilizará…"
      },
      {
        "role": "assistant",
        "content": [
          {
            "type": "text",
            "text": "He leído y comprendido el material de referencia anterior.",
            "cache_control": {
              "type": "ephemeral",
              "ttl": "5m"
            }
          }
        ]
      },
      {
        "role": "user",
        "content": "Resume los tres puntos principales del material de referencia."
      }
    ]
  }'

La primera vez que envíes la solicitud, el sistema intentará crear una caché y la utilizará para completar la solicitud actual.

No es necesario llamar a un endpoint independiente para crear la caché. cache_control define tanto el «límite de la caché» como su «periodo de validez».

Ejemplo de solicitud nativa de Gemini

El endpoint nativo generateContent de Gemini también permite añadir cache_control dentro de contents[].parts[]:

curl "https://api.apimart.ai/v1beta/models/gemini-3.6-flash:generateContent" \
  -H "x-goog-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "systemInstruction": {
      "parts": [
        {
          "text": "Responde estrictamente de acuerdo con el material de referencia proporcionado."
        }
      ]
    },
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "Aquí se incluye el material de referencia extenso que se reutilizará…"
          }
        ]
      },
      {
        "role": "model",
        "parts": [
          {
            "text": "He leído y comprendido el material de referencia anterior.",
            "cache_control": {
              "type": "ephemeral",
              "ttl": "5m"
            }
          }
        ]
      },
      {
        "role": "user",
        "parts": [
          {
            "text": "Resume los tres puntos principales del material de referencia."
          }
        ]
      }
    ]
  }'

cache_control es un campo de extensión de la plataforma para el formato de solicitud de Gemini. Una vez identificado el límite, la plataforma elimina este campo antes de reenviar la solicitud y crea o reutiliza automáticamente el contenido almacenado en caché (cachedContent). La interfaz de streaming usa el mismo cuerpo de solicitud; solo debes cambiar la dirección por:

curl -N "https://api.apimart.ai/v1beta/models/gemini-3.6-flash:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "Aquí se incluye el material de referencia extenso que se reutilizará…",
            "cache_control": {
              "type": "ephemeral",
              "ttl": "5m"
            }
          }
        ]
      },
      {
        "role": "user",
        "parts": [
          {
            "text": "Resume los tres puntos principales del material de referencia."
          }
        ]
      }
    ]
  }'

Al reutilizar la caché, mantén sin cambios systemInstruction, los contents anteriores al límite, el TTL y las tools; modifica únicamente el contenido en tiempo real posterior al límite.

Flujo de creación y reutilización

La primera vez que envíes una solicitud con cache_control:

Identificar el prefijo estable
→ Crear Context Cache
→ Referenciar la nueva caché en la solicitud actual
→ Devolver el resultado del modelo

Cuando vuelvas a enviar el mismo prefijo estable:

Identificar el mismo prefijo estable
→ Reutilizar un Context Cache que no haya caducado
→ Enviar únicamente el contenido actual en tiempo real
→ Devolver el resultado del modelo

Por este motivo, la primera solicitud también puede devolver directamente una cantidad elevada de tokens procedentes de la caché. Es un comportamiento normal y no requiere enviar antes una «solicitud de calentamiento».

Reutilizar la caché

En las solicitudes posteriores, mantén sin cambios lo siguiente:

El modelo
Todos los mensajes anteriores a cache_control
cache_control.ttl
Las definiciones de herramientas (si usas tools)
systemInstruction en las solicitudes nativas de Gemini

Modifica únicamente la pregunta en tiempo real posterior al límite:

{
  "role": "user",
  "content": "¿Qué riesgos se mencionan en el material de referencia?"
}

Siempre que el prefijo estable sea idéntico y la caché no haya caducado, el sistema reutilizará la caché existente. Los siguientes cambios generan una caché diferente:

Modificar el texto o el orden de los mensajes del prefijo estable
Cambiar de modelo
Cambiar 5m por 1h
Modificar las tools o la definición de sus parámetros
Usar un usuario o canal de API diferente

Ejemplo en Python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apimart.ai/v1",
)

stable_messages = [
    {
        "role": "system",
        "content": "Responde estrictamente de acuerdo con el material de referencia proporcionado.",
    },
    {
        "role": "user",
        "content": "Aquí se incluye el material de referencia extenso que se reutilizará…",
    },
    {
        "role": "assistant",
        "content": [
            {
                "type": "text",
                "text": "He leído y comprendido el material de referencia anterior.",
                "cache_control": {
                    "type": "ephemeral",
                    "ttl": "5m",
                },
            }
        ],
    },
]

response = client.chat.completions.create(
    model="gemini-3.6-flash",
    messages=[
        *stable_messages,
        {
            "role": "user",
            "content": "Resume los tres puntos principales del material de referencia.",
        },
    ],
)

print(response.choices[0].message.content)
print(response.usage)

En las solicitudes posteriores, reutiliza el mismo stable_messages y sustituye únicamente el último mensaje del usuario.

Comprobar si se utilizó la caché

Respuesta compatible con OpenAI

Consulta los siguientes campos de la respuesta:

{
  "usage": {
    "prompt_tokens": 14430,
    "prompt_tokens_details": {
      "cached_tokens": 14420,
      "cache_write_tokens": 0
    }
  }
}

Descripción de los campos:

Campo	Significado
`prompt_tokens`	Total de tokens de entrada de esta solicitud
`cached_tokens`	Tokens de entrada leídos de la caché en esta solicitud
`cache_write_tokens`	Tokens escritos en la caché; que devuelva `0` es normal

La primera solicitud también puede mostrar un valor elevado de cached_tokens, ya que el sistema puede crear la caché y referenciarla en la misma llamada al modelo.

Respuesta nativa de Gemini

Consulta usageMetadata.cachedContentTokenCount en la respuesta:

{
  "usageMetadata": {
    "promptTokenCount": 13926,
    "cachedContentTokenCount": 13916,
    "totalTokenCount": 13954
  }
}

Descripción de los campos:

Campo	Significado
`promptTokenCount`	Total de tokens de entrada de esta solicitud
`cachedContentTokenCount`	Tokens de entrada leídos de la caché en esta solicitud
`totalTokenCount`	Total de tokens de entrada y salida de esta solicitud

streamGenerateContent devuelve el mismo usageMetadata en un frame de la respuesta SSE. El cliente debe leer el frame que contiene este campo, no comprobar únicamente el primer fragmento de texto.

Recomendaciones

Almacena en caché únicamente contenido largo que sea realmente estable y vaya a reutilizarse varias veces.
Coloca después del límite de cache_control la pregunta que cambia en cada solicitud.
No incluyas marcas de tiempo, ID aleatorios ni información dinámica del usuario en el prefijo estable.
Usa 5m si prevés repetir las llamadas en un periodo breve.
Usa 1h cuando necesites una ventana de reutilización más larga.
Si el prefijo es demasiado corto, el modelo no es compatible o la caché no está disponible temporalmente, la solicitud puede procesarse automáticamente de la forma habitual.
En el formato nativo de Gemini, el límite de la caché debe estar dentro de contents[].parts[], no en systemInstruction.

Preguntas frecuentes

¿El formato de solicitud nativo de Gemini puede crear una caché automáticamente?

Sí. generateContent y streamGenerateContent usan la misma estructura de cache_control. El límite debe estar dentro de contents[].parts[] y debe quedar al menos un content en tiempo real después del content que contiene el límite.Si la solicitud ya proporciona explícitamente el nombre de un recurso cachedContent nativo, la plataforma da prioridad al recurso indicado por el usuario y no vuelve a crear una caché automáticamente.

¿Por qué no se utilizó la caché?

Estas son algunas causas habituales:

El prefijo estable no coincide exactamente con el de la solicitud anterior
El TTL ha caducado
Se ha modificado el modelo o las tools
El contenido almacenado en caché no alcanza el número mínimo de tokens exigido por el modelo
cache_control está en el último mensaje y no queda ninguna pregunta en tiempo real

¿Puedo colocar cache_control en el último mensaje?

No se recomienda. El último mensaje suele ser la pregunta actual en tiempo real y no debería almacenarse en caché. Si no hay ningún mensaje en tiempo real después del límite, la solicitud se procesa de la forma habitual.

¿Puedo configurar otro TTL?

No. Actualmente solo se admiten 5m y 1h. Cualquier otro valor devuelve un error HTTP 400.

¿Puedo configurar varios límites de caché?

Sí, pero todos los límites deben usar el mismo TTL y el sistema utilizará el último. En general, se recomienda configurar un solo límite por solicitud para que la estructura sea más clara.

¿La solicitud fallará si la caché no está disponible?

Normalmente, no. Si no se cumplen las condiciones para crear o reutilizar la caché, el sistema procesa automáticamente la solicitud de la forma habitual. Se exceptúan los errores de parámetros, como un TTL no válido o el uso combinado de distintos TTL.

¿Qué ocurre si el modelo no tiene habilitado Context Cache?

La solicitud se procesa automáticamente de la forma habitual, sin crear una caché explícita ni generar costes de almacenamiento en caché. La entrada y salida normales, así como cualquier posible coincidencia en una caché implícita, se siguen facturando según las reglas existentes del modelo.

¿Por qué cache_write_tokens es 0?

Es el comportamiento normal de la caché de contexto de Gemini. El coste de creación se registra como un cargo independiente por almacenamiento en caché; no se usa cache_write_tokens, al estilo de OpenAI o Claude, para indicar cuántos tokens se han escrito en la caché.

¿Un valor de cached_tokens superior a 0 significa que se ha creado una caché explícita?

No necesariamente. El propio sistema también puede producir coincidencias en una caché implícita. Para un usuario normal, los tokens leídos de la caché permiten determinar si la solicitud se benefició de una lectura en caché. Si necesitas comprobar el coste de creación de una caché explícita, consulta los registros de consumo de Context Cache storage en la plataforma.

¿Cómo se factura la caché?

Al crear una caché, puede aplicarse una tarifa única de almacenamiento. Al usarla, los tokens coincidentes se facturan al precio de lectura de caché. Consulta los precios específicos en la página de precios de los modelos de la plataforma.

Visión general

Serie de texto

Serie de imágenes

Serie de video

Serie de audio

Serie de Moderación

Gestión de subidas

Gestión de tareas

Gestión de cuenta

Guía de uso de la caché de contexto de Gemini

Casos de uso

Uso básico

Estructura de los mensajes

Ejemplo de solicitud compatible con OpenAI

Ejemplo de solicitud nativa de Gemini

Flujo de creación y reutilización

Reutilizar la caché

Ejemplo en Python

Comprobar si se utilizó la caché

Respuesta compatible con OpenAI

Respuesta nativa de Gemini

Recomendaciones

Preguntas frecuentes

​Casos de uso

​Uso básico

​Estructura de los mensajes

​Ejemplo de solicitud compatible con OpenAI

​Ejemplo de solicitud nativa de Gemini

​Flujo de creación y reutilización

​Reutilizar la caché

​Ejemplo en Python

​Comprobar si se utilizó la caché

​Respuesta compatible con OpenAI

​Respuesta nativa de Gemini

​Recomendaciones

​Preguntas frecuentes

Casos de uso

Uso básico

Estructura de los mensajes

Ejemplo de solicitud compatible con OpenAI

Ejemplo de solicitud nativa de Gemini

Flujo de creación y reutilización

Reutilizar la caché

Ejemplo en Python

Comprobar si se utilizó la caché

Respuesta compatible con OpenAI

Respuesta nativa de Gemini

Recomendaciones

Preguntas frecuentes