Guía de caché de contexto de OpenAI

Para los modelos GPT-5.6 y posteriores que admiten esta función, configura prompt_cache_options.ttl en una solicitud a Responses API para elegir una duración mínima de caché de 30 minutos o 12 horas. Los ejemplos usan gpt-6.1-terra.

La caché de 12 horas solo está disponible en /v1/responses, no en /v1/chat/completions. El TTL indica una duración mínima, no un plazo de eliminación ni una garantía de acierto en cada solicitud.

Configurar la clave API

export API_KEY="YOUR_API_KEY"

El texto largo de los ejemplos es un marcador de posición. Sustitúyelo por el contenido que quieras reutilizar. El prefijo debe tener al menos 1.024 tokens; este texto breve por sí solo no genera una escritura en caché.

Usar la caché de 30 minutos

Establece prompt_cache_options.ttl en "30m". Si omites ttl, también se usan 30 minutos. Si omites mode, se usa la caché implícita: el servicio de origen elige el punto de caché automáticamente.

curl "https://api.apimart.ai/v1/responses" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-6.1-terra",
  "prompt_cache_options": {
    "ttl": "30m"
  },
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Long reference material to reuse (at least 1024 tokens)... Summarize the key points."
        }
      ]
    }
  ]
}'

Usar la caché de 12 horas

Cambia el mismo campo a "12h" y conserva el resto de la estructura:

curl "https://api.apimart.ai/v1/responses" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-6.1-terra",
  "prompt_cache_options": {
    "ttl": "12h"
  },
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Long reference material to reuse (at least 1024 tokens)... Summarize the key points."
        }
      ]
    }
  ]
}'

Reutilizar un prefijo fijo con distintas preguntas

Para reutilizar un documento largo cambiando solo la última pregunta, establece mode en "explicit" y añade prompt_cache_breakpoint al bloque input_text al final del contenido fijo. Este ejemplo usa 12 horas; para 30 minutos, cambia el TTL de la solicitud a "30m".

Configurar mode: "explicit" sin añadir un punto de caché impide leer o escribir en la caché. El punto siguiente no tiene un TTL propio, por lo que hereda prompt_cache_options.ttl de la solicitud.

curl "https://api.apimart.ai/v1/responses" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-6.1-terra",
  "prompt_cache_options": {
    "ttl": "12h",
    "mode": "explicit"
  },
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Long reference material to reuse (at least 1024 tokens)...",
          "prompt_cache_breakpoint": {
            "mode": "explicit"
          }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Summarize the three main points in the reference material."
        }
      ]
    }
  ]
}'

En las siguientes solicitudes envía el mismo modelo, prefijo fijo y punto de caché, cambiando solo el último mensaje del usuario. Mantén el contenido, el orden y los ajustes que afectan al contexto. No necesitas crear ni enviar un ID de caché.

Comprobar el uso de la caché

Revisa usage.input_tokens_details en la respuesta:

cached_tokens: Tokens leídos de la caché en esta solicitud. Un valor mayor que 0 indica una lectura de caché.
cache_write_tokens: Total de tokens escritos en la caché en esta solicitud.
cache_write_tokens_details.ttl_30m_tokens: Tokens escritos con un TTL de 30 minutos en esta solicitud.
cache_write_tokens_details.ttl_12h_tokens: Tokens escritos con un TTL de 12 horas en esta solicitud.

Tras la primera escritura, envía otra solicitud con el mismo prefijo estable y comprueba cached_tokens. Puede ser 0 si el prefijo es demasiado corto, cambia el contenido o no hay un acierto de caché.

Ejemplo de cache usage y recuento de tokens

Este fragmento de respuesta muestra solo usage de un modelo OpenAI compatible con caché, con escrituras para ambos TTL. Los valores reales dependen de la respuesta.

{
  "usage": {
    "input_tokens": 12000,
    "input_tokens_details": {
      "cached_tokens": 4000,
      "cache_write_tokens": 7000,
      "cache_write_tokens_details": {
        "ttl_30m_tokens": 5000,
        "ttl_12h_tokens": 2000
      }
    },
    "output_tokens": 1000,
    "total_tokens": 13000
  }
}

Tokens de entrada ordinarios:

input_tokens - input_tokens_details.cached_tokens - input_tokens_details.cache_write_tokens

cache_write_tokens = ttl_30m_tokens + ttl_12h_tokens
total_tokens = input_tokens + output_tokens

Las lecturas y escrituras de caché ya están incluidas en input_tokens. Las dos cantidades por TTL son componentes de cache_write_tokens: no vuelvas a sumar el total y sus componentes ni añadas las lecturas y escrituras a la entrada total. Aquí, la entrada ordinaria es 12000 - 4000 - 7000 = 1000, las escrituras son 5000 + 2000 = 7000 y el total de tokens es 12000 + 1000 = 13000. Consulta la guía oficial de caché de prompts de OpenAI para conocer su funcionamiento.

Visión general

Modelos

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 caché de contexto de OpenAI

Configurar la clave API

Usar la caché de 30 minutos

Usar la caché de 12 horas

Reutilizar un prefijo fijo con distintas preguntas

Comprobar el uso de la caché

Ejemplo de cache usage y recuento de tokens

​Configurar la clave API

​Usar la caché de 30 minutos

​Usar la caché de 12 horas

​Reutilizar un prefijo fijo con distintas preguntas

​Comprobar el uso de la caché

​Ejemplo de cache usage y recuento de tokens

Configurar la clave API

Usar la caché de 30 minutos

Usar la caché de 12 horas

Reutilizar un prefijo fijo con distintas preguntas

Comprobar el uso de la caché

Ejemplo de cache usage y recuento de tokens