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:

• Almacenamiento en caché automático: Agrega un único campo cache_control en el nivel superior de tu solicitud. El sistema aplica automáticamente el "cache breakpoint" (punto de interrupción de caché) al último bloque almacenable en caché y lo mueve hacia adelante a medida que crecen las conversaciones. Es ideal para conversaciones de múltiples turnos en las que 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 tener un control detallado sobre exactamente qué se almacena en caché.

La forma más sencilla de empezar es con el almacenamiento en caché automático:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-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 almacenamiento en caché automático, el sistema almacena en caché todo el contenido hasta el último bloque almacenable en caché, inclusive. 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é a partir de una consulta reciente.
2. Si lo encuentra, usa la versión en caché, lo que reduce 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 almacenado 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 hacer streaming, una solicitud de seguimiento que reutilice el mismo prefijo en caché debe comenzar aproximadamente dentro de 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:

Model	Base tokens		Prompt caching
Name	Input	Output	5m writes	1h writes	Hits and refreshes
Claude Fable 5.1For demanding reasoning and long-horizon agentic work	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$0.25 / MTok1
Claude Opus 5.5For long-running agentic coding and knowledge work	$4 / MTok	$20 / MTok	$5 / MTok	$8 / MTok	$0.20 / MTok2
Claude Sonnet 5.5The best combination of speed and intelligence	$2 / MTok	$10 / MTok	$2.50 / MTok	$4 / MTok	$0.20 / MTok
Claude Haiku 4.5The fastest model with near-frontier intelligence	$1 / MTok	$5 / MTok	$1.25 / MTok	$2 / MTok	$0.10 / MTok
Additional models
Claude Mythos 5.1	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$0.25 / MTok1
Claude Fable 5	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$1 / MTok
Claude Mythos 5	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$1 / MTok
Claude Opus 5	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.8	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.7	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.6	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.5	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.1	$15 / MTok	$75 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok
Claude Opus 4	$15 / MTok	$75 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok
Claude Sonnet 5	$2 / MTok	$10 / MTok	$2.50 / MTok	$4 / MTok	$0.20 / MTok
Claude Sonnet 4.6	$3 / MTok	$15 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok
Claude Sonnet 4.5	$3 / MTok	$15 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok
Claude Sonnet 4	$3 / MTok	$15 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok
Claude Haiku 3.5	$0.80 / MTok	$4 / MTok	$1 / MTok	$1.60 / MTok	$0.08 / MTok

^{1 Cache hits and refreshes on Claude Fable 5.1 and Claude Mythos 5.1 are priced at 0.025x the base input price.}

^{2 Cache hits and refreshes on Claude Opus 5.5 are priced at 0.05x the base input price.}

^{All other models use the standard 0.1x multiplier.}

Modelos compatibles

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

Almacenamiento en caché automático

El almacenamiento en 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 almacenable en caché.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-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 almacenamiento en caché automático en conversaciones de múltiples turnos

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

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

Compatibilidad con TTL

De forma predeterminada, el almacenamiento en caché automático usa un "TTL" (tiempo de vida) 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 el almacenamiento en caché a nivel de bloque

El almacenamiento en 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 ocupa 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 el almacenamiento en caché automático se encarga de la conversación:

{
  "model": "claude-opus-5-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?" }]
}

Lo que se mantiene igual

El almacenamiento en caché automático usa la misma infraestructura de caché subyacente. Los precios, los umbrales mínimos de tokens, los requisitos de orden del contexto y la ventana de retrospección de 20 bloques se aplican de la misma manera que con los puntos de interrupción explícitos.

Casos límite

• Si el último bloque ya tiene un cache_control explícito con el mismo TTL, el almacenamiento en caché automático no tiene ningún 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 almacenamiento en caché automático).
• Si el último bloque no es apto como destino de un punto de interrupción de caché automático, el sistema retrocede silenciosamente para encontrar el bloque apto más cercano. Si no 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 distintas frecuencias, o cuando 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 almacenarlo en caché usando el parámetro cache_control.

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

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

Puedes usar un solo 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 haya escrito en la caché. Entender 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. Como el hash es acumulativo y abarca todo hasta el punto de interrupción, inclusive, cambiar cualquier bloque en el punto de interrupción o antes de él produce un hash diferente en la siguiente solicitud.

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

3. La "lookback window" (ventana de retrospección) es de 20 bloques. El sistema verifica como máximo 20 posiciones por punto de interrupción, contando el propio punto de interrupción 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). En la Claude API, una serie de bloques tool_use consecutivos cuenta como una sola posición, al igual que una serie de bloques tool_result consecutivos, por lo que un turno con muchas llamadas a herramientas en paralelo no saca por sí solo la entrada de la solicitud anterior fuera de la ventana.

Ejemplo: Retrospección 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é previas. 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 desde cero solo los bloques 11 a 15 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, por lo que no hay acierto de caché. Agregar un segundo punto de interrupción en el bloque 15 inicia allí una segunda ventana de retrospección, 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 es diferente, por lo que el hash del prefijo en el bloque 6 es diferente. La retrospección 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 nueva escritura en caché en cada solicitud y nunca obtienes una lectura.

La retrospección no encuentra contenido estable detrás de tu punto de interrupción para almacenarlo 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 se mantiene igual entre solicitudes, y cada solicitud posterior leerá el prefijo en caché. El almacenamiento en caché automático cae en la misma trampa: coloca el punto de interrupción en el último bloque almacenable en caché, 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 en 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, por lo que la retrospección 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 distintas frecuencias (por ejemplo, las herramientas rara vez cambian, pero el contexto se actualiza a diario)
• Tener más control sobre exactamente qué se almacena en caché
• Garantizar 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é

Entender los costos de los puntos de interrupción de caché

Los puntos de interrupción de caché en sí 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 un TTL de 5 minutos)
• Lecturas de caché: Cuando se usa contenido en caché (10% del precio base de los tokens de entrada, o 2.5% en Claude Fable 5.1 y Claude Mythos 5.1, y 5% en Claude Opus 5.5)
• Tokens de entrada regulares: Por 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 el contenido que realmente se almacena en caché y se lee. Los puntos de interrupción te dan control sobre qué secciones pueden almacenarse en caché de forma independiente.

Estrategias y consideraciones de almacenamiento en caché

Limitaciones de la caché

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

• 512 tokens para Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.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 esta cantidad 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 se queda justo por debajo del mínimo para tu modelo y plataforma, a menudo vale la pena ampliar 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 de los prompts que se reutilizan 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 en paralelo, espera la primera respuesta antes de enviar las 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 de la solicitud se pueden almacenar en caché. Esto incluye:

• Herramientas: Definiciones de herramientas en el arreglo tools
• Mensajes del sistema: Bloques de contenido en el arreglo system
• Mensajes de texto: Bloques de contenido en el arreglo messages.content, tanto para turnos del usuario como del asistente
• Imágenes y documentos: Bloques de contenido en el arreglo messages.content, en turnos del usuario
• Uso de herramientas y resultados de herramientas: Bloques de contenido en el arreglo messages.content, tanto en turnos del usuario como del 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 la 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 desde la caché.

• Los bloques de subcontenido (como las citas) 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 sí se pueden almacenar en caché. Esto te permite usar el almacenamiento en caché de prompts con citas de forma eficaz, almacenando en caché los documentos a los que harán referencia las citas.

• 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 la totalidad de 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 con distintos tipos de cambios. ✘ indica que la caché se invalida, mientras que ✓ indica que la caché sigue siendo válida.

En los modelos que admiten cambios de herramientas a mitad de la conversación, el encabezado beta inline-tools-2026-09-15 te permite agregar una herramienta, o cambiar la definición de una herramienta, a mitad de una conversación sin editar tools. Envía la definición en un bloque tool_addition dentro de un mensaje del sistema a mitad de la conversación y deja tools exactamente como lo enviaste la primera vez. El prefijo en caché sigue coincidiendo, por lo que solo el mensaje agregado se procesa como entrada nueva. La única excepción es un arreglo tools sin ninguna herramienta no diferida, en cuyo caso la primera herramienta definida de esta manera cuesta un fallo de caché completo en esa solicitud. Consulta Definir herramientas en un mensaje.

Seguimiento del rendimiento de la caché

Supervisa el rendimiento de la caché usando estos campos de respuesta de la API, dentro de usage en la respuesta (o en 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 una caché ni se usaron para crearla (es decir, los tokens después del último punto de interrupción de caché).

Almacenamiento en caché con bloques de pensamiento

Cuando usas 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 suele ocurrir durante el uso de herramientas, cuando devuelves los bloques de pensamiento para continuar la conversación.

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

Patrones de invalidación de la caché:

• La caché sigue siendo válida cuando solo se proporcionan resultados de herramientas como mensajes del 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 un resultado de herramienta, por lo que la caché sigue siendo válida
• En modelos Opus/Sonnet anteriores y en todos los modelos Haiku, la caché se invalida cuando se agrega contenido de usuario que no es un resultado de herramienta, lo que provoca 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 obtener más detalles sobre la invalidación de la 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 en 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 conservan de forma predeterminada y siguen formando 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 la caché

• Aislamiento por organización y espacio de trabajo: Las cachés están aisladas entre organizaciones. Las distintas organizaciones nunca comparten cachés, incluso si usan prompts idénticos. Las cachés también están aisladas por espacio de trabajo dentro de una organización en la Claude API, 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, incluidos todo el texto y las imágenes hasta el bloque marcado con control de caché, inclusive.

• Generación de tokens de salida: El almacenamiento en caché de prompts no tiene ningún 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é eficaz

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

• Empieza con el almacenamiento en caché automático para conversaciones de múltiples turnos. Gestiona los 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 distintas 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é de forma estratégica para separar diferentes secciones de prefijo almacenables en caché.
• Coloca el punto de interrupción en el último bloque que se mantiene 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 periódicamente 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 "latency" (latencia) en conversaciones extensas, especialmente aquellas con instrucciones largas o documentos cargados.
• Asistentes de programación: Mejora el autocompletado y las preguntas y respuestas sobre la base de código manteniendo en el prompt las secciones relevantes o una versión resumida de la base de código.
• Procesamiento de documentos grandes: Incorpora material extenso completo, incluidas imágenes, en tu prompt sin aumentar la latencia de respuesta.
• Conjuntos de instrucciones detalladas: Comparte listas extensas de instrucciones, procedimientos y ejemplos para ajustar con precisión las respuestas de Claude. Los desarrolladores suelen incluir 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 en escenarios que implican múltiples llamadas a herramientas y cambios de código iterativos, donde cada paso normalmente requiere una nueva llamada a la API.
• Conversar con libros, artículos, documentación, transcripciones de podcasts y otro contenido extenso: Da vida a cualquier base de conocimiento incorporando el documento o los 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 los puntos de interrupción explícitos, verifica que los marcadores cache_control estén en las mismas ubicaciones
• Comprueba 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 se mantengan 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 la caché)
• Confirma que tu punto de interrupción esté en un bloque que se mantiene 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 retrospección 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 de 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, lo que rompe las cachés
• Usa el diagnóstico 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 la 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 del objeto cache_creation.

Si ves escrituras 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), sigue usando la caché de 5 minutos, ya que esta se seguirá actualizando sin cargo adicional.

La caché de 1 hora es más adecuada 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 agente secundario 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 el aprovechamiento de tu límite de velocidad, ya que los aciertos de caché no se descuentan de tu límite de velocidad.

Mezclar diferentes TTL

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 un "time to live" (tiempo de vida), o 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 TTL, la API determina tres ubicaciones de facturación en tu prompt:

1. Posición A: el recuento de tokens en el "cache hit" (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 de caché de 1 hora para (B - A).
3. Tokens de escritura de caché de 5 minutos para (C - B).

Aquí tienes tres ejemplos. Esto representa los tokens de entrada de 3 solicitudes, cada una de las cuales tiene diferentes aciertos y fallos de caché. Como resultado, cada una tiene un precio calculado diferente, que se muestra en los recuadros de colores.

Precalentar la caché

El "cache pre-warming" (precalentamiento de caché) te permite cargar tu indicación del sistema o tus 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, en 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 "breakpoint" (punto de interrupción) de cache_control, y luego responde de inmediato sin generar ninguna salida. La respuesta tiene un arreglo 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 posterior (normalmente tu indicación del sistema o tus definiciones de herramientas), no en el mensaje de usuario de relleno. De lo contrario, la entrada de caché queda asociada al mensaje de relleno y la solicitud posterior no la aprovechará. Usa también la misma configuración de pensamiento y el mismo output_config.effort que en tus solicitudes posteriores: 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 aprovecha. Esto implica usar un punto de interrupción de caché explícito en lugar del 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 mensaje de relleno. El mensaje de usuario de relleno 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-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 devuelve un arreglo content vacío:

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [],
  "model": "claude-opus-5-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 se inicie tu aplicación (o en un intervalo programado) y luego envía las solicitudes reales de los usuarios una vez que el precalentamiento haya terminado:

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-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-5",
        max_tokens=1024,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": user_message}],
    )


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

# Después, 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 usuarios, usa en su lugar la duración de caché de 1 hora.

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 está orientado al tiempo hasta el primer token, que 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 posterior.

Reemplazar 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. Se prefiere el enfoque de max_tokens: 0: no se produce ninguna salida, por lo que no hay una respuesta de un solo token que descartar, no se factura ningún token 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 "prompt caching" (almacenamiento en caché de prompts), el cookbook de almacenamiento en caché de prompts ofrece ejemplos detallados y buenas 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 función:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing legal documents.",
        },
        {
            "type": "text",
            "text": "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
            "cache_control": {"type": "ephemeral"},
        },
    ],
    messages=[
        {
            "role": "user",
            "content": "What are the key terms and conditions in this agreement?",
        }
    ],
)
print(response.usage.model_dump_json())

{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "tools": [
    {
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "input_schema": {
        "type": "object",
        "properties": { "location": { "type": "string" } },
        "required": ["location"]
      }
    },
    {
      "name": "get_time",
      "description": "Get the current time in a given time zone",
      "input_schema": {
        "type": "object",
        "properties": { "timezone": { "type": "string" } },
        "required": ["timezone"]
      },
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "What is the weather and time in New York?" }]
}

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "...long system prompt",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[
        # ...conversación larga hasta ahora
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Hello, can you tell me more about the solar system?",
                }
            ],
        },
        {
            "role": "assistant",
            "content": "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you'd like to know more about?",
        },
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Good to know."},
                {
                    "type": "text",
                    "text": "Tell me more about Mars.",
                    "cache_control": {"type": "ephemeral"},
                },
            ],
        },
    ],
)
print(response.usage.model_dump_json())

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=[
        {
            "name": "search_documents",
            "description": "Search through the knowledge base",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "Search query"}
                },
                "required": ["query"],
            },
        },
        {
            "name": "get_document",
            "description": "Retrieve a specific document by ID",
            "input_schema": {
                "type": "object",
                "properties": {
                    "doc_id": {"type": "string", "description": "Document ID"}
                },
                "required": ["doc_id"],
            },
            "cache_control": {"type": "ephemeral"},
        },
    ],
    system=[
        {
            "type": "text",
            "text": "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",
            "cache_control": {"type": "ephemeral"},
        },
        {
            "type": "text",
            "text": "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",
            "cache_control": {"type": "ephemeral"},
        },
    ],
    messages=[
        {
            "role": "user",
            "content": "Can you search for information about Mars rovers?",
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "tool_use",
                    "id": "tool_1",
                    "name": "search_documents",
                    "input": {"query": "Mars rovers"},
                }
            ],
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "tool_1",
                    "content": "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",
                }
            ],
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.",
                }
            ],
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Yes, please tell me about the Perseverance rover specifically.",
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
    ],
)
print(response.usage.model_dump_json())

Retención de datos

El almacenamiento en caché de prompts (tanto automático como explícito) es apto para "zero data retention" (retención de datos cero), o ZDR. Anthropic no almacena el texto sin procesar de tus prompts ni de 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 una vida útil mínima de 5 minutos (estándar) o 1 hora (extendida), tras la cual se eliminan con prontitud, aunque no de inmediato. Las entradas de caché están aisladas entre organizaciones y, en la Claude API, Claude Platform on AWS y Microsoft Foundry, entre espacios de trabajo dentro de una organización.

Para conocer la aptitud para ZDR de todas las funciones, consulta API y retención de datos.

Preguntas frecuentes

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

client.beta.prompt_caching.messages.create(**params)

client.messages.create(**params)

client.beta.promptCaching.messages.create(/* ... */);

client.messages.create(/* ... */);