Almacenamiento en caché de prompts

El "prompt caching" (almacenamiento en caché de prompts) optimiza tu uso de la API al permitir reanudar desde prefijos específicos en tus prompts. Esto reduce significativamente el tiempo de procesamiento y los costos para tareas repetitivas o prompts con elementos consistentes.

Hay dos formas de habilitar el almacenamiento en caché de prompts:

• Caché automático: Agrega un único campo cache_control en el nivel superior de tu solicitud. El sistema aplica automáticamente el punto de interrupción de caché al último bloque cacheable y lo mueve hacia adelante a medida que las conversaciones crecen. Ideal para conversaciones de múltiples turnos donde el historial de mensajes creciente debe almacenarse en caché automáticamente.
• Puntos de interrupción de caché explícitos: Coloca cache_control directamente en bloques de contenido individuales para un control detallado sobre exactamente qué se almacena en caché.

La forma más sencilla de comenzar es con el caché automático:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
    messages=[
        {
            "role": "user",
            "content": "Analyze the major themes in 'Pride and Prejudice'.",
        }
    ],
)
print(response.usage.model_dump_json())

Con el caché automático, el sistema almacena en caché todo el contenido hasta e incluyendo el último bloque cacheable. En solicitudes posteriores con el mismo prefijo, el contenido en caché se reutiliza automáticamente.



Cómo funciona el almacenamiento en caché de prompts

Cuando envías una solicitud con el almacenamiento en caché de prompts habilitado:

1. El sistema verifica si un prefijo del prompt, hasta un punto de interrupción de caché especificado, ya está almacenado en caché de una consulta reciente.
2. Si lo encuentra, usa la versión en caché, reduciendo el tiempo de procesamiento y los costos.
3. De lo contrario, procesa el prompt completo y almacena en caché el prefijo una vez que comienza la respuesta.

Esto es especialmente útil para:

• Prompts con muchos ejemplos
• Grandes cantidades de contexto o información de fondo
• Tareas repetitivas con instrucciones consistentes
• Conversaciones largas de múltiples turnos

De forma predeterminada, la caché tiene una vida útil de 5 minutos. La caché se actualiza sin costo adicional cada vez que se usa el contenido en caché.

La vida útil se mide desde el inicio de la solicitud que escribe o lee la entrada de caché, no desde el final de su respuesta. El tiempo dedicado a generar una respuesta cuenta contra la vida útil: si una respuesta tarda 4 minutos en transmitirse por streaming, una solicitud de seguimiento que reutilice el mismo prefijo en caché debe comenzar dentro de aproximadamente 1 minuto después de que se complete esa respuesta.



Precios

El almacenamiento en caché de prompts introduce una nueva estructura de precios. La siguiente tabla muestra el precio por millón de tokens para cada modelo compatible:



Modelos compatibles

El almacenamiento en caché de prompts (tanto automático como explícito) es compatible con todos los modelos activos de Claude.



Caché automático

El caché automático es la forma más sencilla de habilitar el almacenamiento en caché de prompts. En lugar de colocar cache_control en bloques de contenido individuales, agrega un único campo cache_control en el nivel superior del cuerpo de tu solicitud. El sistema aplica automáticamente el punto de interrupción de caché al último bloque cacheable.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are a helpful assistant that remembers our conversation.",
    messages=[
        {"role": "user", "content": "My name is Alex. I work on machine learning."},
        {
            "role": "assistant",
            "content": "Nice to meet you, Alex! How can I help with your ML work today?",
        },
        {"role": "user", "content": "What did I say I work on?"},
    ],
)
print(response.usage.model_dump_json())



Cómo funciona el caché automático en conversaciones de múltiples turnos

Con el caché automático, el punto de caché avanza automáticamente a medida que las conversaciones crecen. Cada nueva solicitud almacena en caché todo hasta el último bloque cacheable, y el contenido anterior se lee desde la caché.

El punto de interrupción de caché se mueve automáticamente al último bloque cacheable en cada solicitud, por lo que no necesitas actualizar ningún marcador cache_control a medida que la conversación crece.



Compatibilidad con TTL

De forma predeterminada, el caché automático usa un TTL de 5 minutos. Puedes especificar un TTL de 1 hora a 2 veces el precio base de los tokens de entrada:

{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }



Combinación con caché a nivel de bloque

El caché automático es compatible con los puntos de interrupción de caché explícitos. Cuando se usan juntos, el punto de interrupción de caché automático usa uno de los 4 espacios de puntos de interrupción disponibles.

Esto te permite combinar ambos enfoques. Por ejemplo, usa un punto de interrupción explícito para almacenar en caché tu indicación del sistema, mientras que el caché automático maneja la conversación:

{
  "model": "claude-opus-5",
  "max_tokens": 1024,
  "cache_control": { "type": "ephemeral" },
  "system": [
    {
      "type": "text",
      "text": "You are a helpful assistant.",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "What are the key terms?" }]
}



Qué permanece igual

El caché automático usa la misma infraestructura de caché subyacente. Los precios, los umbrales mínimos de tokens, los requisitos de ordenamiento de contexto y la ventana de búsqueda hacia atrás de 20 bloques se aplican de la misma manera que con los puntos de interrupción explícitos.



Casos especiales

• Si el último bloque ya tiene un cache_control explícito con el mismo TTL, el caché automático no tiene efecto.
• Si el último bloque tiene un cache_control explícito con un TTL diferente, la API devuelve un error 400.
• Si ya existen 4 puntos de interrupción explícitos a nivel de bloque, la API devuelve un error 400 (no quedan espacios para el caché automático).
• Si el último bloque no es elegible como objetivo de punto de interrupción de caché automático, el sistema retrocede silenciosamente para encontrar el bloque elegible más cercano. Si no se encuentra ninguno, se omite el almacenamiento en caché.



Puntos de interrupción de caché explícitos

Para tener más control sobre el almacenamiento en caché, puedes colocar cache_control directamente en bloques de contenido individuales. Esto es útil cuando necesitas almacenar en caché diferentes secciones que cambian con diferentes frecuencias, o necesitas un control detallado sobre exactamente qué se almacena en caché.



Estructurar tu prompt

Coloca el contenido estático (definiciones de herramientas, instrucciones del sistema, contexto, ejemplos) al principio de tu prompt. Marca el final del contenido reutilizable para el almacenamiento en caché usando el parámetro cache_control.

Los prefijos de caché se crean en el siguiente orden: tools, system, luego messages. Este orden forma una jerarquía donde cada nivel se construye sobre los anteriores.



Cómo funciona la verificación automática de prefijos

Puedes usar solo un punto de interrupción de caché al final de tu contenido estático, y el sistema encontrará automáticamente el prefijo más largo que una solicitud anterior ya escribió en la caché. Comprender cómo funciona esto te ayuda a optimizar tu estrategia de almacenamiento en caché.

Tres principios fundamentales:

1. Las escrituras en caché ocurren solo en tu punto de interrupción. Marcar un bloque con cache_control escribe exactamente una entrada de caché: un hash del prefijo que termina en ese bloque. El sistema no escribe entradas para ninguna posición anterior. Debido a que el hash es acumulativo, cubriendo todo hasta e incluyendo el punto de interrupción, cambiar cualquier bloque en o antes del punto de interrupción produce un hash diferente en la siguiente solicitud.

2. Las lecturas de caché buscan hacia atrás entradas que solicitudes anteriores escribieron. En cada solicitud, el sistema calcula el hash del prefijo en tu punto de interrupción y verifica si hay una entrada de caché coincidente. Si no existe ninguna, retrocede un bloque a la vez, verificando si el hash del prefijo en cada posición anterior coincide con algo que ya está en la caché. Está buscando escrituras anteriores, no contenido estable.

3. La ventana de búsqueda hacia atrás es de 20 bloques. El sistema verifica como máximo 20 posiciones por punto de interrupción, contando el punto de interrupción mismo como la primera. Si el sistema no encuentra ninguna entrada coincidente en esa ventana, la verificación se detiene (o se reanuda desde el siguiente punto de interrupción explícito, si lo hay).

Ejemplo: Búsqueda hacia atrás en una conversación creciente

Agregas nuevos bloques en cada turno y estableces cache_control en el bloque final de cada solicitud:

• Turno 1: 10 bloques, punto de interrupción en el bloque 10. No existen entradas de caché anteriores. El sistema escribe una entrada en el bloque 10.
• Turno 2: 15 bloques, punto de interrupción en el bloque 15. El bloque 15 no tiene entrada, así que el sistema retrocede hasta el bloque 10 y encuentra la entrada del turno 1. Acierto de caché en el bloque 10; el sistema procesa solo los bloques 11 a 15 como nuevos y escribe una nueva entrada en el bloque 15.
• Turno 3: 35 bloques, punto de interrupción en el bloque 35. El sistema verifica 20 posiciones (bloques 35 a 16) y no encuentra nada. La entrada del turno 2 en el bloque 15 está una posición fuera de la ventana, así que no hay acierto de caché. Agregar un segundo punto de interrupción en el bloque 15 inicia una segunda ventana de búsqueda hacia atrás allí, que encuentra la entrada del turno 2.

Error común: Punto de interrupción en contenido que cambia en cada solicitud

Tu prompt tiene un contexto de sistema estático grande (bloques 1 a 5) seguido de un bloque por solicitud que contiene una marca de tiempo y el mensaje del usuario (bloque 6). Estableces cache_control en el bloque 6:

• Solicitud 1: Escritura en caché en el bloque 6. El hash incluye la marca de tiempo.
• Solicitud 2: La marca de tiempo difiere, así que el hash del prefijo en el bloque 6 difiere. La búsqueda hacia atrás recorre los bloques 5, 4, 3, 2 y 1, pero el sistema nunca escribió una entrada en ninguna de esas posiciones. No hay acierto de caché. Pagas por una escritura en caché nueva en cada solicitud y nunca obtienes una lectura.

La búsqueda hacia atrás no encuentra contenido estable detrás de tu punto de interrupción y lo almacena en caché. Encuentra entradas que solicitudes anteriores ya escribieron, y las escrituras ocurren solo en los puntos de interrupción. Mueve cache_control al bloque 5, el último bloque que permanece igual entre solicitudes, y cada solicitud posterior lee el prefijo en caché. El caché automático cae en la misma trampa: coloca el punto de interrupción en el último bloque cacheable, que en esta estructura es el que cambia en cada solicitud, así que usa un punto de interrupción explícito en el bloque 5 en su lugar.

Conclusión clave: Coloca cache_control en el último bloque cuyo prefijo sea idéntico entre las solicitudes que quieres que compartan una caché. En una conversación creciente, el bloque final funciona siempre que cada turno agregue menos de 20 bloques: el contenido anterior nunca cambia, así que la búsqueda hacia atrás de la siguiente solicitud encuentra la escritura anterior. Para un prompt con un sufijo variable (marcas de tiempo, contexto por solicitud, el mensaje entrante), coloca el punto de interrupción al final del prefijo estático, no en el bloque variable.



Cuándo usar múltiples puntos de interrupción

Puedes definir hasta 4 puntos de interrupción de caché si quieres:

• Almacenar en caché diferentes secciones que cambian con diferentes frecuencias (por ejemplo, las herramientas rara vez cambian, pero el contexto se actualiza diariamente)
• Tener más control sobre exactamente qué se almacena en caché
• Asegurar un acierto de caché cuando una conversación creciente empuja tu punto de interrupción 20 o más bloques más allá de la última escritura en caché



Comprender los costos de los puntos de interrupción de caché

Los puntos de interrupción de caché en sí mismos no agregan ningún costo. Solo se te cobra por:

• Escrituras en caché: Cuando se escribe contenido nuevo en la caché (25% más que los tokens de entrada base para TTL de 5 minutos)
• Lecturas de caché: Cuando se usa contenido en caché (10% del precio base de los tokens de entrada)
• Tokens de entrada regulares: Para cualquier contenido no almacenado en caché

Agregar más puntos de interrupción cache_control no aumenta tus costos: sigues pagando la misma cantidad según qué contenido se almacena en caché y se lee realmente. Los puntos de interrupción te dan control sobre qué secciones se pueden almacenar en caché de forma independiente.



Estrategias y consideraciones de almacenamiento en caché



Limitaciones de caché

En la API de Claude, Claude Platform on AWS, Google Cloud y Microsoft Foundry, la longitud mínima de prompt cacheable es:

• 512 tokens para Claude Opus 5, Claude Fable 5 y Claude Mythos 5
• 2,048 tokens para Claude Mythos Preview y Claude Opus 4.7
• 4,096 tokens para Claude Opus 4.6 y Claude Opus 4.5
• 1,024 tokens para Claude Opus 4.8, Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Opus 4.1 (retirado, excepto en Bedrock y Google Cloud), Claude Opus 4 (retirado, excepto en Google Cloud) y Claude Sonnet 4 (retirado, excepto en Bedrock y Google Cloud)
• 4,096 tokens para Claude Haiku 4.5
• 2,048 tokens para Claude Haiku 3.5 (retirado, excepto en Bedrock y Google Cloud)

Estos mínimos se aplican en todas las plataformas donde cada modelo está disponible.

Los prompts más cortos no se pueden almacenar en caché, incluso si están marcados con cache_control. Cualquier solicitud para almacenar en caché menos de este número de tokens se procesará sin almacenamiento en caché, y no se devuelve ningún error. Para verificar si un prompt se almacenó en caché, revisa los campos de uso de la respuesta: si tanto cache_creation_input_tokens como cache_read_input_tokens son 0, el prompt no se almacenó en caché (probablemente porque no cumplió con el requisito de longitud mínima).

Si tu prompt queda justo por debajo del mínimo para tu modelo y plataforma, a menudo vale la pena expandir el contenido en caché para alcanzar el umbral. Las lecturas de caché cuestan significativamente menos que los tokens de entrada no almacenados en caché, por lo que alcanzar el mínimo puede reducir los costos para prompts reutilizados con frecuencia.

Para solicitudes concurrentes, ten en cuenta que una entrada de caché solo está disponible después de que comienza la primera respuesta. Si necesitas aciertos de caché para solicitudes paralelas, espera la primera respuesta antes de enviar solicitudes posteriores.

Actualmente, "ephemeral" es el único tipo de caché compatible, que de forma predeterminada tiene una vida útil de 5 minutos.



Qué se puede almacenar en caché

La mayoría de los bloques en la solicitud se pueden almacenar en caché. Esto incluye:

• Herramientas: Definiciones de herramientas en el array tools
• Mensajes del sistema: Bloques de contenido en el array system
• Mensajes de texto: Bloques de contenido en el array messages.content, tanto para turnos de usuario como de asistente
• Imágenes y documentos: Bloques de contenido en el array messages.content, en turnos de usuario
• Uso de herramientas y resultados de herramientas: Bloques de contenido en el array messages.content, tanto en turnos de usuario como de asistente

Cada uno de estos elementos se puede almacenar en caché, ya sea automáticamente o marcándolos con cache_control.



Qué no se puede almacenar en caché

Aunque la mayoría de los bloques de solicitud se pueden almacenar en caché, hay algunas excepciones:

• Los bloques de pensamiento no se pueden almacenar en caché directamente con cache_control. Sin embargo, los bloques de pensamiento SÍ se pueden almacenar en caché junto con otro contenido cuando aparecen en turnos anteriores del asistente. Cuando se almacenan en caché de esta manera, SÍ cuentan como tokens de entrada cuando se leen de la caché.

• Los bloques de subcontenido (como las citas) en sí mismos no se pueden almacenar en caché directamente. En su lugar, almacena en caché el bloque de nivel superior.

  En el caso de las citas, los bloques de contenido de documento de nivel superior que sirven como material fuente para las citas se pueden almacenar en caché. Esto te permite usar el almacenamiento en caché de prompts con citas de manera efectiva al almacenar en caché los documentos a los que las citas harán referencia.

• Los bloques de texto vacíos no se pueden almacenar en caché.



Qué invalida la caché

Las modificaciones al contenido en caché pueden invalidar parte o toda la caché.

Como se describe en Estructurar tu prompt, la caché sigue la jerarquía: tools → system → messages. Los cambios en cada nivel invalidan ese nivel y todos los niveles posteriores.

La siguiente tabla muestra qué partes de la caché se invalidan por diferentes tipos de cambios. ✘ indica que la caché se invalida, mientras que ✓ indica que la caché permanece válida.



Seguimiento del rendimiento de la caché

Monitorea el rendimiento de la caché usando estos campos de respuesta de la API, dentro de usage en la respuesta (o el evento message_start si usas streaming):

• cache_creation_input_tokens: Número de tokens escritos en la caché al crear una nueva entrada.
• cache_read_input_tokens: Número de tokens recuperados de la caché para esta solicitud.
• input_tokens: Número de tokens de entrada que no se leyeron de la caché ni se usaron para crear una caché (es decir, tokens después del último punto de interrupción de caché).



Almacenamiento en caché con bloques de pensamiento

Al usar pensamiento con almacenamiento en caché de prompts, los bloques de pensamiento tienen un comportamiento especial:

Almacenamiento en caché automático junto con otro contenido: Aunque los bloques de pensamiento no se pueden marcar explícitamente con cache_control, se almacenan en caché como parte del contenido de la solicitud cuando realizas llamadas posteriores a la API con resultados de herramientas. Esto ocurre comúnmente durante el uso de herramientas cuando pasas bloques de pensamiento de vuelta para continuar la conversación.

Conteo de tokens de entrada: Cuando los bloques de pensamiento se leen de la caché, cuentan como tokens de entrada en tus métricas de uso. Esto es importante para el cálculo de costos y la presupuestación de tokens.

Patrones de invalidación de caché:

• La caché permanece válida cuando solo se proporcionan resultados de herramientas como mensajes de usuario
• En Opus 4.5+ y Sonnet 4.6+, los bloques de pensamiento se conservan de forma predeterminada incluso cuando se agrega contenido de usuario que no es resultado de herramientas, por lo que la caché permanece válida
• En modelos Opus/Sonnet anteriores y todos los modelos Haiku, la caché se invalida cuando se agrega contenido de usuario que no es resultado de herramientas, lo que hace que todos los bloques de pensamiento anteriores se eliminen del contexto
• Este comportamiento de almacenamiento en caché ocurre incluso sin marcadores cache_control explícitos

Para más detalles sobre la invalidación de caché, consulta Qué invalida la caché.

Ejemplo con uso de herramientas:

Request 1: User: "What's the weather in Paris?"
Response: [thinking_block_1] + [tool_use block 1]

Request 2:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True]
Response: [thinking_block_2] + [text block 2]
# Request 2 caches its request content (not the response)
# The cache includes: user message, thinking_block_1, tool_use block 1, and tool_result_1

Request 3:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]
# On earlier Opus/Sonnet and all Haiku models, non-tool-result user block causes prior thinking blocks to be stripped; on Opus 4.5+/Sonnet 4.6+ they are kept

En modelos Opus/Sonnet anteriores y todos los modelos Haiku, todos los bloques de pensamiento anteriores se eliminan del contexto en este punto. En Opus 4.5+ y Sonnet 4.6+, los bloques de pensamiento anteriores se mantienen de forma predeterminada y siguen siendo parte del prefijo en caché.

Para obtener información más detallada, consulta Pensamiento y almacenamiento en caché de prompts.



Almacenamiento y uso compartido de caché

• Aislamiento de organización y workspace: Las cachés están aisladas entre organizaciones. Diferentes organizaciones nunca comparten cachés, incluso si usan prompts idénticos. Las cachés también están aisladas por workspace dentro de una organización en la API de Claude, Claude Platform on AWS y Microsoft Foundry; Bedrock y Google Cloud usan solo aislamiento a nivel de organización.

• Coincidencia exacta: Los aciertos de caché requieren segmentos de prompt 100% idénticos, incluyendo todo el texto e imágenes hasta e incluyendo el bloque marcado con cache control.

• Generación de tokens de salida: El almacenamiento en caché de prompts no tiene efecto en la generación de tokens de salida. La respuesta que recibes es idéntica a la que obtendrías si no se usara el almacenamiento en caché de prompts.



Mejores prácticas para un almacenamiento en caché efectivo

Para optimizar el rendimiento del almacenamiento en caché de prompts:

• Comienza con el caché automático para conversaciones de múltiples turnos. Maneja la gestión de puntos de interrupción automáticamente.
• Usa puntos de interrupción explícitos a nivel de bloque cuando necesites almacenar en caché diferentes secciones con diferentes frecuencias de cambio.
• Almacena en caché contenido estable y reutilizable como instrucciones del sistema, información de fondo, contextos grandes o definiciones de herramientas frecuentes.
• Coloca el contenido en caché al principio del prompt para obtener el mejor rendimiento.
• Usa los puntos de interrupción de caché estratégicamente para separar diferentes secciones de prefijo cacheables.
• Coloca el punto de interrupción en el último bloque que permanece idéntico entre solicitudes. Para un prompt con un prefijo estático y un sufijo variable (marcas de tiempo, contexto por solicitud, el mensaje entrante), ese es el final del prefijo, no el bloque variable.
• Analiza regularmente las tasas de aciertos de caché y ajusta tu estrategia según sea necesario.



Optimización para diferentes casos de uso

Adapta tu estrategia de almacenamiento en caché de prompts a tu escenario:

• Agentes conversacionales: Reduce el costo y la latencia para conversaciones extendidas, especialmente aquellas con instrucciones largas o documentos cargados.
• Asistentes de programación: Mejora el autocompletado y las preguntas y respuestas sobre bases de código manteniendo secciones relevantes o una versión resumida de la base de código en el prompt.
• Procesamiento de documentos grandes: Incorpora material completo de formato largo, incluyendo imágenes, en tu prompt sin aumentar la latencia de respuesta.
• Conjuntos de instrucciones detalladas: Comparte listas extensas de instrucciones, procedimientos y ejemplos para afinar las respuestas de Claude. Los desarrolladores a menudo incluyen uno o dos ejemplos en el prompt, pero con el almacenamiento en caché de prompts puedes obtener un rendimiento aún mejor incluyendo más de 20 ejemplos diversos de respuestas de alta calidad.
• Uso de herramientas agéntico: Mejora el rendimiento para escenarios que involucran múltiples llamadas a herramientas y cambios iterativos de código, donde cada paso normalmente requiere una nueva llamada a la API.
• Conversa con libros, artículos, documentación, transcripciones de podcasts y otro contenido de formato largo: Da vida a cualquier base de conocimiento incorporando el documento o documentos completos en el prompt y permitiendo que los usuarios le hagan preguntas.



Solución de problemas comunes

Si experimentas un comportamiento inesperado:

• Asegúrate de que las secciones en caché sean idénticas entre llamadas. Para puntos de interrupción explícitos, verifica que los marcadores cache_control estén en las mismas ubicaciones
• Verifica que las llamadas se realicen dentro de la vida útil de la caché (5 minutos de forma predeterminada)
• Verifica que tool_choice, el uso de imágenes, la configuración de pensamiento y output_config.effort permanezcan consistentes entre llamadas
• Valida que estés almacenando en caché al menos el número mínimo de tokens para tu modelo y plataforma (consulta Limitaciones de caché)
• Confirma que tu punto de interrupción esté en un bloque que permanece idéntico entre solicitudes. Las escrituras en caché ocurren solo en el punto de interrupción, y si ese bloque cambia (marcas de tiempo, contexto por solicitud, el mensaje entrante), el hash del prefijo nunca coincide. La búsqueda hacia atrás no encuentra contenido estable detrás del punto de interrupción; solo encuentra entradas que solicitudes anteriores escribieron en sus propios puntos de interrupción
• Verifica que las claves en tus bloques de contenido tool_use tengan un orden estable, ya que algunos lenguajes (por ejemplo, Swift, Go) aleatorizan el orden de las claves durante la conversión a JSON, rompiendo las cachés
• Usa diagnósticos de caché para que la API compare solicitudes consecutivas e informe qué parte del prompt divergió



Duración de caché de 1 hora

Si consideras que 5 minutos es muy poco tiempo, Anthropic también ofrece una duración de caché de 1 hora con un costo adicional.

Para usar la caché extendida, incluye ttl en la definición de cache_control de esta manera:

"cache_control": {
  "type": "ephemeral",
  "ttl": "1h"
}

La respuesta incluye información detallada de caché como la siguiente:

{
  "usage": {
    "input_tokens": 2048,
    "cache_read_input_tokens": 1800,
    "cache_creation_input_tokens": 248,
    "output_tokens": 503,

    "cache_creation": {
      "ephemeral_5m_input_tokens": 148,
      "ephemeral_1h_input_tokens": 100
    }
  }
}

Ten en cuenta que el campo actual cache_creation_input_tokens es igual a la suma de los valores en el objeto cache_creation.

Si ves escrituras de ephemeral_5m_input_tokens que no solicitaste mientras usas herramientas de servidor como la búsqueda web, consulta Uso de herramientas con almacenamiento en caché de prompts.



Cuándo usar la caché de 1 hora

Si tienes prompts que se usan con una cadencia regular (es decir, indicaciones del sistema que se usan con más frecuencia que cada 5 minutos), continúa usando la caché de 5 minutos, porque esta seguirá actualizándose sin cargo adicional.

La caché de 1 hora se usa mejor en los siguientes escenarios:

• Cuando tienes prompts que probablemente se usen con menos frecuencia que cada 5 minutos, pero con más frecuencia que cada hora. Por ejemplo, cuando un subagente agéntico tardará más de 5 minutos, o cuando almacenas una conversación de chat larga con un usuario y generalmente esperas que ese usuario no responda en los próximos 5 minutos.
• Cuando la latencia es importante y tus prompts de seguimiento pueden enviarse después de 5 minutos.
• Cuando quieres mejorar la utilización de tu límite de velocidad, porque los aciertos de caché no se deducen de tu límite de velocidad.



Mezclar diferentes TTLs

Puedes usar controles de caché de 1 hora y de 5 minutos en la misma solicitud, pero con una restricción importante: las entradas de caché con TTL más largo deben aparecer antes que las de TTL más corto (es decir, una entrada de caché de 1 hora debe aparecer antes que cualquier entrada de caché de 5 minutos).

Al mezclar TTLs, la API determina tres ubicaciones de facturación en tu prompt:

1. Posición A: El recuento de tokens en el acierto de caché más alto (o 0 si no hay aciertos).
2. Posición B: El recuento de tokens en el bloque cache_control de 1 hora más alto después de A (o igual a A si no existe ninguno).
3. Posición C: El recuento de tokens en el último bloque cache_control.

Se te cobrará por:

1. Tokens de lectura de caché para A.
2. Tokens de escritura en caché de 1 hora para (B - A).
3. Tokens de escritura en caché de 5 minutos para (C - B).

Aquí hay tres ejemplos. Esto representa los tokens de entrada de 3 solicitudes, cada una de las cuales tiene diferentes aciertos y fallos de caché. Cada una tiene un precio calculado diferente, mostrado en los cuadros de colores, como resultado.



Precalentar la caché

El precalentamiento de caché te permite cargar tu indicación del sistema o definiciones de herramientas en la caché de prompts antes de que un usuario active una solicitud real. Esto elimina la penalización de latencia por fallo de caché en la primera interacción del usuario, reduciendo el "time-to-first-token" (tiempo hasta el primer token), o TTFT, para aplicaciones sensibles a la latencia.



Cómo funciona

Establece max_tokens: 0 en tu solicitud. La API lee tu prompt en el modelo y escribe la caché en cualquier punto de interrupción cache_control, luego retorna inmediatamente sin generar ninguna salida. La respuesta tiene un array content vacío, stop_reason: "max_tokens", y un bloque usage completamente poblado.

Coloca el punto de interrupción cache_control en el último bloque que se comparte con la solicitud de seguimiento (típicamente tu indicación del sistema o definiciones de herramientas), no en el mensaje de usuario de marcador de posición. De lo contrario, la entrada de caché queda asociada al marcador de posición y la solicitud de seguimiento no la encontrará. Usa también la misma configuración de pensamiento y output_config.effort que tus solicitudes de seguimiento: esos valores se renderizan en el prompt (consulta Qué invalida la caché), por lo que un precalentamiento con una configuración diferente puede escribir una entrada que tu tráfico real nunca encontrará. Esto significa usar un punto de interrupción de caché explícito en lugar de almacenamiento en caché automático, ya que el almacenamiento en caché automático coloca el punto de interrupción en el último bloque, que aquí es el marcador de posición. El mensaje de usuario de marcador de posición puede ser cualquier cadena con contenido que no sea solo espacios en blanco (los ejemplos aquí usan "warmup"); su contenido se lee en el modelo pero nunca se responde.

client = anthropic.Anthropic()

# Ejecuta esto antes de que lleguen los usuarios para precalentar la caché compartida de la indicación del sistema.
prewarm = client.messages.create(
    model="claude-opus-5",
    max_tokens=0,
    system=[
        {
            "type": "text",
            "text": "You are an expert software engineer with deep knowledge of distributed systems...",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "warmup"}],
)
print(prewarm.stop_reason)  # "max_tokens"
print(prewarm.content)  # []
print(prewarm.usage)

La API retorna un array content vacío:

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [],
  "model": "claude-opus-5",
  "stop_reason": "max_tokens",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 8,
    "cache_creation_input_tokens": 5120,
    "cache_read_input_tokens": 0,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 5120,
      "ephemeral_1h_input_tokens": 0
    },
    "iterations": [
      {
        "input_tokens": 8,
        "output_tokens": 0,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 5120,
        "cache_creation": {
          "ephemeral_5m_input_tokens": 5120,
          "ephemeral_1h_input_tokens": 0
        },
        "type": "message"
      }
    ],
    "output_tokens": 0,
    "service_tier": "standard",
    "inference_geo": "global"
  }
}



Patrón de uso típico

Lanza una solicitud de precalentamiento cuando tu aplicación inicie (o en un intervalo programado), luego envía solicitudes reales de usuario después de que el precalentamiento se complete:

client = anthropic.Anthropic()

SYSTEM_PROMPT = [
    {
        "type": "text",
        "text": "You are an expert software engineer with deep knowledge of distributed systems...",
        "cache_control": {"type": "ephemeral"},
    }
]


def prewarm_cache() -> None:
    """Call this at application startup or on a scheduled interval."""
    client.messages.create(
        model="claude-opus-5",
        max_tokens=0,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": "warmup"}],
    )


def respond(user_message: str) -> anthropic.types.Message:
    """The real user request; benefits from a warm cache."""
    return client.messages.create(
        model="claude-opus-5",
        max_tokens=1024,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": user_message}],
    )


# Calienta la caché antes de que llegue cualquier tráfico de usuarios.
prewarm_cache()

# Más tarde, cuando el usuario envía un mensaje, el prefijo de la indicación del sistema ya está en caché.
response = respond("How do I implement a binary search tree?")
for block in response.content:
    if block.type == "text":
        print(block.text)

Ten en cuenta que el TTL de la caché sigue aplicándose. Para la caché predeterminada de 5 minutos, envía una nueva solicitud de precalentamiento al menos cada 5 minutos para mantener la caché caliente. Para intervalos más largos entre solicitudes de usuario, usa la duración de caché de 1 hora en su lugar.



Limitaciones

Una solicitud con max_tokens: 0 se rechaza con un invalid_request_error si se establece cualquiera de los siguientes, ya que cada uno implica una salida que un presupuesto de cero tokens no puede producir:

• stream: true
• Pensamiento extendido (thinking.type: "enabled")
• Salidas estructuradas (output_config.format)
• tool_choice de {"type": "tool", ...} o {"type": "any"}

max_tokens: 0 también se rechaza dentro de una solicitud de Message Batches. El precalentamiento apunta al tiempo hasta el primer token, lo cual no aplica al procesamiento por lotes, y una entrada de caché escrita durante el procesamiento por lotes probablemente expiraría antes de que se ejecute la solicitud de seguimiento.



Reemplazando la solución alternativa de max_tokens=1

Antes de que max_tokens: 0 estuviera disponible, algunas aplicaciones usaban llamadas de calentamiento con max_tokens: 1 para lograr el mismo efecto. El enfoque de max_tokens: 0 es preferible: no se produce ninguna salida, por lo que no hay una respuesta de un solo token que descartar, no se facturan tokens de salida, y la intención de la solicitud es inequívoca.



Ejemplos de almacenamiento en caché de prompts

Para ayudarte a comenzar con el almacenamiento en caché de prompts, el cookbook de almacenamiento en caché de prompts proporciona ejemplos detallados y mejores prácticas.

Los siguientes fragmentos de código muestran varios patrones de almacenamiento en caché de prompts. Estos ejemplos demuestran cómo implementar el almacenamiento en caché en diferentes escenarios, ayudándote a comprender las aplicaciones prácticas de esta funcionalidad:



Retención de datos

El almacenamiento en caché de prompts (tanto automático como explícito) es elegible para ZDR. Anthropic no almacena el texto sin procesar de tus prompts ni las respuestas de Claude.

Las representaciones de caché KV (clave-valor) y los hashes criptográficos del contenido almacenado en caché se mantienen solo en memoria y no se almacenan en reposo. Las entradas almacenadas en caché tienen un tiempo de vida mínimo de 5 minutos (estándar) o 1 hora (extendido), después del cual se eliminan de forma rápida, aunque no inmediata. Las entradas de caché están aisladas entre organizaciones y, en la API de Claude, Claude Platform en AWS y Microsoft Foundry, entre espacios de trabajo dentro de una organización.

Para la elegibilidad de ZDR en todas las funcionalidades, consulta API y retención de datos.



Preguntas frecuentes