Opciones y Referencia de Precios de TTL de Caché

Una referencia rápida para las dos ventanas de TTL (tiempo de vida) de caché que Claude soporta, cuánto cuesta cada una en relación con un token de entrada normal y cómo seleccionar una en el bloque cache_control.

Cómo Usar Esta Referencia

• Utiliza esta página para decidir entre el TTL predeterminado de 5 minutos y el TTL extendido de 1 hora para una carga de trabajo dada.
• Trata el comportamiento de precios descrito aquí como cualitativo y relativo; confirma siempre los multiplicadores exactos actuales en platform.claude.com/docs antes de presupuestar, ya que los precios se mueven independientemente de esta página.
• Empareja esta referencia con usage.cache_read_input_tokens y usage.cache_creation_input_tokens en respuestas reales para validar tus suposiciones frente al tráfico real.
• Revisa tu elección de TTL cada vez que cambie tu cadencia de solicitudes; una carga de trabajo que solía activarse cada pocos segundos y ahora se activa cada pocos minutos puede necesitar un TTL más largo para seguir accediendo a la caché.

Opciones de TTL de un Vistazo

• Ambos TTL son efímeros: la expiración de la entrada de caché se reinicia en cada acceso a la caché, por lo que un flujo constante de solicitudes dentro de la ventana mantiene la entrada viva indefinidamente.
• Una lectura de caché (cache_read_input_tokens) siempre se factura a una tarifa más baja que un token de entrada normal, independientemente de qué TTL escribió la entrada.
• Una escritura de caché (cache_creation_input_tokens) cuesta más que un token de entrada normal en ambos TTL; el multiplicador de escritura del TTL de 1 hora es más alto que el multiplicador de escritura del TTL de 5 minutos, ya que pagas por una garantía de mayor duración.
• Los multiplicadores exactos varían según el modelo y cambian con el tiempo; esta página evita intencionalmente citar cantidades fijas en dólares.

Configuración del TTL en Python

import anthropic
 
client = anthropic.Anthropic()
 
# TTL predeterminado de 5 minutos - omite "ttl" por completo o configúralo explícitamente.
system_5m = [
    {
        "type": "text",
        "text": "Eres el asistente de soporte de Acme Corp." * 50,
        "cache_control": {"type": "ephemeral"},
    }
]
 
# TTL extendido de 1 hora - clave "ttl" explícita.
system_1h = [
    {
        "type": "text",
        "text": "Eres el asistente de soporte de Acme Corp." * 50,
        "cache_control": {"type": "ephemeral", "ttl": "1h"},
    }
]
 
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=200,
    system=system_1h,
    messages=[{"role": "user", "content": "¿Cuál es tu ventana de reembolso?"}],
)

Decidiendo Entre los Dos

1. Estima tu cadencia de solicitudes. Si las solicitudes consecutivas que comparten un prefijo están típicamente a segundos o un par de minutos de distancia, el predeterminado de 5 minutos suele ser suficiente y más barato de escribir.
2. Estima la duración de la sesión. Si una sola sesión de usuario o agente puede tener brechas de 10 minutos o más entre llamadas que reutilizan el mismo prefijo (sesiones de investigación largas, revisión con intervención humana, pipelines de lotes lentos), el TTL de 1 hora evita incurrir repetidamente en el costo de escritura de la caché.
3. Pondera el costo de escritura frente al recuento de accesos esperado. Un multiplicador de escritura más alto se amortiza una vez que obtienes suficientes lecturas de caché contra esa escritura; un prefijo reutilizado solo una o dos veces no recupera el costo de escritura de ninguno de los TTL.
4. Por defecto, usa 5 minutos a menos que tengas una razón específica. Es la escritura más barata y se adapta a la mayoría de las cargas de trabajo interactivas y de ráfaga; utiliza la opción de 1 hora deliberadamente, no por defecto.
5. Reevalúa después de medir, no antes. Instrumenta usage.cache_read_input_tokens y usage.cache_creation_input_tokens en producción y revisa la elección del TTL basándote en las tasas de aciertos observadas en lugar de una suposición.

Verificando Qué TTL se Aplicó Realmente

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=200,
    system=system_1h,
    messages=[{"role": "user", "content": "¿Cuál es tu ventana de reembolso?"}],
)
 
usage = response.usage
print(f"tokens de escritura de caché: {usage.cache_creation_input_tokens}")
print(f"tokens de lectura de caché:  {usage.cache_read_input_tokens}")
print(f"tokens de entrada normales: {usage.input_tokens}")

• Un valor distinto de cero en cache_creation_input_tokens con cero cache_read_input_tokens significa que esta llamada escribió la caché por primera vez (o después de que expirara).
• Un valor distinto de cero en cache_read_input_tokens significa que la solicitud accedió a una entrada existente bajo el TTL que la escribió.
• La respuesta no refleja directamente qué TTL se utilizó; rastrea eso por tu cuenta, ya que lo estableciste en la solicitud.

Preguntas Frecuentes

Relacionado

• Cómo funciona realmente la coincidencia de prefijos del almacenamiento en caché de prompts - el mecanismo que rigen estos TTL.
• Conceptos básicos del almacenamiento en caché de prompts - configura tu primer TTL en una solicitud funcional.
• Verificación de aciertos de caché con cache_read_input_tokens - confirma qué TTL está dando resultados.
• ROI del almacenamiento en caché de prompts - Cuándo las escrituras de caché realmente valen la pena - las matemáticas de costo-beneficio con más detalle.

Versiones de la pila: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5 - y el SDK oficial de Python anthropic (última versión 0.x). Los nombres de los modelos, las versiones del SDK y los precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.