> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Guía de caché de contexto de OpenAI

> Usa la caché de 30 minutos o 12 horas mediante Responses API para reutilizar prompts, documentos y prefijos de conversación estables.

Para los modelos GPT-5.6 y posteriores que admiten esta función, configura `prompt_cache_options.ttl` en una solicitud a [Responses API](https://docs.apimart.ai/es/api-reference/texts/openai/responses.md) para elegir una duración mínima de caché de 30 minutos o 12 horas. Los ejemplos usan `gpt-6.1-terra`.

> [!NOTE]
>
> 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

```bash theme={null}
export API_KEY="YOUR_API_KEY"
```

> [!NOTE]
>
> 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.

```bash theme={null}
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:

```bash theme={null}
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"`.

> [!NOTE]
>
> 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.

```bash theme={null}
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.

```json theme={null}
{
  "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:

```text theme={null}
input_tokens - input_tokens_details.cached_tokens - input_tokens_details.cache_write_tokens
```

```text theme={null}
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](https://developers.openai.com/api/docs/guides/prompt-caching) para conocer su funcionamiento.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.