Prompt Caching en 2026: Guía de Costo y Latencia

Paso 1 — Anthropic: marcá el prefijo estable

Agregá cache_control a los bloques que casi no cambian. Dejá el mensaje fresco del usuario sin marcar y reutilizá el mismo prefijo exacto en la próxima llamada. Mirá usage para cache_creation_input_tokens en la primera y cache_read_input_tokens después.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model=“claude-sonnet-4-5-20250929”,
    max_tokens=1024,
    system=[
        {
            “type”: “text”,
            “text”: SYSTEM_PROMPT,  # instrucciones largas y estables
            “cache_control”: {“type”: “ephemeral”},
        }
    ],
    messages=[{“role”: “user”, “content”: user_question}],
)

print(response.usage.cache_creation_input_tokens)
print(response.usage.cache_read_input_tokens)

Paso 2 — Anthropic: elegí el TTL a conciencia

El TTL default es 5 minutos. Para loops agénticos o conversaciones largas donde los follow-ups pueden tardar, poné ttl en “1h” — duplica el precio de escritura pero las lecturas siguen a 0.1x. Mezclá ambos TTLs solo con las entradas de 1 hora antes que las de 5 minutos.

system=[
    {
        “type”: “text”,
        “text”: SYSTEM_PROMPT,
        “cache_control”: {“type”: “ephemeral”, “ttl”: “1h”},
    }
]

# O caching automático: un solo marcador top-level,
# el breakpoint sigue al último bloque cacheable.
response = client.messages.create(
    model=“claude-sonnet-4-5-20250929”,
    max_tokens=1024,
    cache_control={“type”: “ephemeral”},
    system=[{“type”: “text”, “text”: SYSTEM_PROMPT}],
    messages=[{“role”: “user”, “content”: user_question}],
)

Paso 3 — OpenAI: elegí un modo y marcá un breakpoint

En GPT-5.6 y posteriores, dejá el modo implícito default para threads que solo agregan mensajes, o poné prompt_cache_options.mode en “explicit” y marcá el fin del contenido estable con prompt_cache_breakpoint para que el sufijo cambiante nunca se escriba a 1.25x. Reutilizá un prompt_cache_key estable, mantené el prefijo ≥ 1.024 tokens con TTL 30m (default, único valor), y después leé cached_tokens y cache_write_tokens. Pre-5.6: solo automático, mínimo 2.048 tokens, escrituras gratis, prompt_cache_retention en vez de prompt_cache_options.

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model=“gpt-5.6”,
    prompt_cache_key=“my-app-v1:session-42”,
    prompt_cache_options={“mode”: “explicit”, “ttl”: “30m”},
    input=[
        {
            “role”: “developer”,
            “content”: [
                {
                    “type”: “input_text”,
                    “text”: LONG_SYSTEM_PROMPT,  # estable, >= 1.024 tokens
                    “prompt_cache_breakpoint”: {“mode”: “explicit”},
                }
            ],
        },
        {“role”: “user”, “content”: user_question},  # dinámico al final
    ],
)

print(response.usage.input_tokens_details.cached_tokens)
print(response.usage.input_tokens_details.cache_write_tokens)
# Pre-5.6: solo automático, mín 2.048 tokens, escrituras gratis,
# prompt_cache_retention (in_memory / 24h), redondeo a 128 tokens.

Paso 4 — Gemini: confiá en lo implícito, pasá a explícito

En Gemini 2.5+ hacé el mismo orden estable-primero y el caching implícito funciona solo — revisá usageMetadata para los tokens cacheados. Cuando necesites reuso garantizado de un corpus grande (docs, repo, video), creá un caché explícito con TTL y referenciá su nombre en llamadas siguientes.

from google import genai

client = genai.Client()

cache = client.caches.create(
    model=“gemini-2.5-flash”,
    config={
        “system_instruction”: LONG_SYSTEM_PROMPT,
        “contents”: [LARGE_DOCUMENT_CORPUS],
        “ttl”: “3600s”,
    },
)

response = client.models.generate_content(
    model=“gemini-2.5-flash”,
    contents=f“Pregunta: {user_question}”,
    config={“cached_content”: cache.name},
)

print(response.usage_metadata)

1. Contenido dinámico antes que el estable

Un timestamp, user ID o snippet RAG cambiante al tope del prompt cambia el hash del prefijo y cada request es un miss. Fix: mové todo lo variable después de los bloques cacheados.

2. Prefijo bajo el mínimo, marcado igual

Anthropic y Gemini ignoran las marcas en prefijos bajo el mínimo del modelo (1.024–4.096 tokens según modelo). Los prompts cortos no cachean nada — sin error, sin ahorro. Fix: marcá solo bloques que superen el umbral; verificalo con el contador de tokens.

3. Schemas de tools serializados en orden aleatorio

Iterar dicts o regenerar JSON con claves mezcladas produce un prefijo distinto a nivel byte en cada llamada. Fix: serializá las tools de forma determinística (claves ordenadas, orden fijo) para que el prefijo coincida byte por byte.

4. TTL más corto que los huecos de tu conversación

Un TTL de 5 minutos en un bot de soporte donde los usuarios responden a los 20 minutos hace que cada turno sea una escritura fresca. Fix: medí los gaps entre requests y usá el TTL de 1 hora (Claude) o caché explícito con TTL largo (Gemini) cuando los gaps superen minutos.

5. Conversaciones que crecen más que la ventana

En Claude, un solo breakpoint puede quedar fuera de la ventana de 20 bloques a medida que crece el historial, cortando los hits a mitad de sesión sin aviso. Fix: agregá un segundo breakpoint cerca de la cola que crece — uno para instrucciones estables, otro tras el historial reciente.