Almacenamiento en caché de indicaciones

El almacenamiento en caché de indicaciones optimiza el uso de tu API permitiendo reanudar desde prefijos específicos en tus indicaciones. Esto reduce significativamente el tiempo de procesamiento y los costos para tareas repetitivas o indicaciones con elementos consistentes.

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

• Almacenamiento en caché automático: Añade un único campo cache_control en el nivel superior de tu solicitud. El sistema aplica automáticamente el punto de ruptura de caché al último bloque almacenable en caché y lo mueve hacia adelante a medida que crecen las conversaciones. Mejor para conversaciones de múltiples turnos donde el historial de mensajes en crecimiento debe almacenarse en caché automáticamente.
• Puntos de ruptura de caché explícitos: Coloca cache_control directamente en bloques de contenido individuales para un control granular sobre exactamente qué se almacena en caché.

La forma más simple de comenzar es con almacenamiento en caché automático:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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 almacenamiento en caché automático, el sistema almacena en caché todo el contenido hasta e incluyendo el último bloque almacenable en caché. En solicitudes posteriores con el mismo prefijo, el contenido almacenado en caché se reutiliza automáticamente.

Cómo funciona el almacenamiento en caché de indicaciones

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

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

Esto es especialmente útil para:

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

Por defecto, el caché tiene una vida útil de 5 minutos. El caché se actualiza sin costo adicional cada vez que se utiliza el contenido almacenado en caché.

Precios

El almacenamiento en caché de indicaciones introduce una nueva estructura de precios. La tabla a continuación muestra el precio por millón de tokens para cada modelo soportado:

Modelos soportados

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

Almacenamiento en caché automático

El almacenamiento en caché automático es la forma más simple de habilitar el almacenamiento en caché de indicaciones. En lugar de colocar cache_control en bloques de contenido individuales, añade un único campo cache_control en el nivel superior del cuerpo de tu solicitud. El sistema aplica automáticamente el punto de ruptura de caché al último bloque almacenable en caché.

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

Con almacenamiento en caché automático, el punto de caché se mueve hacia adelante 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 el caché.

El punto de ruptura 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.

Soporte de TTL

Por defecto, el almacenamiento en caché automático utiliza un TTL de 5 minutos. Puedes especificar un TTL de 1 hora a 2 veces el precio de token de entrada base:

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

Combinación con almacenamiento en caché a nivel de bloque

El almacenamiento en caché automático es compatible con puntos de ruptura de caché explícitos. Cuando se usan juntos, el punto de ruptura de caché automático utiliza uno de los 4 espacios de punto de ruptura disponibles.

Esto te permite combinar ambos enfoques. Por ejemplo, usa puntos de ruptura explícitos para almacenar en caché tu indicación de sistema y herramientas de forma independiente, mientras que el almacenamiento en caché automático maneja la conversación:

{
  "model": "claude-opus-4-7",
  "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 permanece igual

El almacenamiento en caché automático utiliza la misma infraestructura de almacenamiento en caché subyacente. Los precios, los umbrales de token mínimo, los requisitos de ordenamiento de contexto y la ventana de retrospectiva de 20 bloques se aplican igual que con puntos de ruptura explícitos.

Casos extremos

• Si el último bloque ya tiene un cache_control explícito con el mismo TTL, el almacenamiento en caché automático es una no-operación.
• 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 ruptura explícitos a nivel de bloque, la API devuelve un error 400 (no hay espacios disponibles para almacenamiento en caché automático).
• Si el último bloque no es elegible como objetivo de punto de ruptura de caché automático, el sistema camina silenciosamente hacia atrás para encontrar el bloque elegible más cercano. Si no se encuentra ninguno, el almacenamiento en caché se omite.

Puntos de ruptura de caché explícitos

Para 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 a diferentes frecuencias, o necesitas control granular sobre exactamente qué se almacena en caché.

Estructuración de tu indicación

Coloca contenido estático (definiciones de herramientas, instrucciones del sistema, contexto, ejemplos) al principio de tu indicación. Marca el final del contenido reutilizable para 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 ruptura 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 el caché. Entender cómo funciona esto te ayuda a optimizar tu estrategia de almacenamiento en caché.

Tres principios fundamentales:

1. Las escrituras de caché ocurren solo en tu punto de ruptura. 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. Porque el hash es acumulativo, cubriendo todo hasta e incluyendo el punto de ruptura, cambiar cualquier bloque en o antes del punto de ruptura produce un hash diferente en la siguiente solicitud.

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

3. La ventana de retrospectiva es de 20 bloques. El sistema verifica como máximo 20 posiciones por punto de ruptura, contando el punto de ruptura mismo como el primero. Si el sistema no encuentra una entrada coincidente en esa ventana, la verificación se detiene (o se reanuda desde el siguiente punto de ruptura explícito, si existe).

Ejemplo: Retrospectiva en una conversación en crecimiento

Añades nuevos bloques cada turno y estableces cache_control en el bloque final de cada solicitud:

• Turno 1: 10 bloques, punto de ruptura en bloque 10. No existen entradas de caché anteriores. El sistema escribe una entrada en bloque 10.
• Turno 2: 15 bloques, punto de ruptura en bloque 15. El bloque 15 no tiene entrada, por lo que el sistema camina hacia atrás al bloque 10 y encuentra la entrada del turno 1. Acierto de caché en bloque 10; el sistema procesa solo bloques 11 a 15 frescos y escribe una nueva entrada en bloque 15.
• Turno 3: 35 bloques, punto de ruptura en bloque 35. El sistema verifica 20 posiciones (bloques 35 a 16) y no encuentra nada. La entrada del turno 2 en bloque 15 está una posición fuera de la ventana, por lo que no hay acierto de caché. Añadir un segundo punto de ruptura en bloque 15 inicia una segunda ventana de retrospectiva allí, que encuentra la entrada del turno 2.

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

Tu indicación tiene un gran contexto de sistema estático (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 bloque 6:

• Solicitud 1: Escritura de caché en bloque 6. El hash incluye la marca de tiempo.
• Solicitud 2: La marca de tiempo difiere, por lo que el hash de prefijo en bloque 6 difiere. La retrospectiva camina a través de bloques 5, 4, 3, 2 y 1, pero el sistema nunca escribió una entrada en ninguna de esas posiciones. Sin acierto de caché. Pagas por una escritura de caché fresca en cada solicitud y nunca obtienes una lectura.

La retrospectiva no encuentra contenido estable detrás de tu punto de ruptura y lo almacena en caché. Encuentra entradas que solicitudes anteriores ya escribieron, y las escrituras ocurren solo en puntos de ruptura. Mueve cache_control al bloque 5, el último bloque que permanece igual en todas las solicitudes, y cada solicitud posterior lee el prefijo almacenado en caché. El almacenamiento en caché automático cae en la misma trampa: coloca el punto de ruptura en el último bloque almacenable en caché, que en esta estructura es el que cambia cada solicitud, por lo que usa un punto de ruptura explícito en bloque 5 en su lugar.

Conclusión clave: Coloca cache_control en el último bloque cuyo prefijo es idéntico en las solicitudes que deseas compartir un caché. En una conversación en crecimiento, el bloque final funciona siempre que cada turno añada menos de 20 bloques: el contenido anterior nunca cambia, por lo que la retrospectiva de la siguiente solicitud encuentra la escritura anterior. Para una indicación con un sufijo variable (marcas de tiempo, contexto por solicitud, el mensaje entrante), coloca el punto de ruptura al final del prefijo estático, no en el bloque variable.

Cuándo usar múltiples puntos de ruptura

Puedes definir hasta 4 puntos de ruptura de caché si deseas:

• Almacenar en caché diferentes secciones que cambian a 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 en crecimiento empuja tu punto de ruptura 20 o más bloques más allá de la última escritura de caché

Entendimiento de costos de puntos de ruptura de caché

Los puntos de ruptura de caché en sí no añaden ningún costo. Solo se te cobra por:

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

Añadir más puntos de ruptura cache_control no aumenta tus costos - aún pagas la misma cantidad basada en qué contenido se almacena en caché y se lee realmente. Los puntos de ruptura simplemente te dan control sobre qué secciones pueden almacenarse en caché de forma independiente.

Estrategias de almacenamiento en caché y consideraciones

Limitaciones de caché

La longitud mínima de indicación almacenable en caché es:

• 4096 tokens para Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6, y Claude Opus 4.5
• 2048 tokens para Claude Sonnet 4.6
• 1024 tokens para Claude Sonnet 4.5, Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4, y Claude Sonnet 3.7 (deprecado)
• 4096 tokens para Claude Haiku 4.5
• 2048 tokens para Claude Haiku 3.5 (deprecado) y Claude Haiku 3

Las indicaciones más cortas no pueden almacenarse en caché, incluso si se marcan 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 una indicación fue almacenada en caché, verifica los campos de uso de respuesta: si tanto cache_creation_input_tokens como cache_read_input_tokens son 0, la indicación no fue almacenada en caché (probablemente porque no cumplió el requisito de longitud mínima).

Si tu indicación cae justo por debajo del mínimo para el modelo que estás usando, expandir el contenido almacenado en caché para alcanzar el umbral a menudo vale la pena. Las lecturas de caché cuestan significativamente menos que tokens de entrada no almacenados en caché, por lo que alcanzar el mínimo puede reducir costos para indicaciones reutilizadas frecuentemente.

Para solicitudes concurrentes, ten en cuenta que una entrada de caché solo se vuelve 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é soportado, que por defecto tiene una vida útil de 5 minutos.

Qué puede almacenarse en caché

La mayoría de bloques en la solicitud pueden almacenarse 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, para turnos de usuario y 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, en turnos de usuario y asistente

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

Qué no puede almacenarse en caché

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

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

• Los bloques de sub-contenido (como citas) en sí no pueden almacenarse en caché directamente. En su lugar, almacena en caché el bloque de nivel superior.

  En el caso de citas, los bloques de contenido de documento de nivel superior que sirven como material de origen para citas pueden almacenarse en caché. Esto te permite usar almacenamiento en caché de indicaciones con citas de manera efectiva almacenando en caché los documentos que las citas referenciarán.

• Los bloques de texto vacío no pueden almacenarse en caché.

Qué invalida el caché

Las modificaciones al contenido almacenado en caché pueden invalidar parte o todo el caché.

Como se describe en Estructuración de tu indicación, el 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 del caché se invalidan por diferentes tipos de cambios. ✘ indica que el caché se invalida, mientras que ✓ indica que el caché permanece válido.

Seguimiento del rendimiento de caché

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

• cache_creation_input_tokens: Número de tokens escritos en el caché al crear una nueva entrada.
• cache_read_input_tokens: Número de tokens recuperados del caché para esta solicitud.
• input_tokens: Número de tokens de entrada que no fueron leídos de o utilizados para crear un caché (es decir, tokens después del último punto de ruptura de caché).

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

Almacenamiento en caché con bloques de pensamiento

Cuando se utiliza pensamiento extendido con almacenamiento en caché de indicaciones, los bloques de pensamiento tienen un comportamiento especial:

Almacenamiento en caché automático junto con otro contenido: Aunque los bloques de pensamiento no pueden marcarse explícitamente con cache_control, se almacenan en caché como parte del contenido de la solicitud cuando realiza llamadas API posteriores con resultados de herramientas. Esto ocurre comúnmente durante el uso de herramientas cuando pasa bloques de pensamiento de vuelta 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 sus 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 del usuario
• La caché se invalida cuando se agrega contenido de usuario que no es resultado de herramientas, lo que causa que todos los bloques de pensamiento anteriores se eliminen
• Este comportamiento de almacenamiento en caché ocurre incluso sin marcadores cache_control explícitos

Para más detalles sobre la invalidación de caché, consulte 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]
# Non-tool-result user block causes all thinking blocks to be ignored
# This request is processed as if thinking blocks were never present

Cuando se incluye un bloque de usuario que no es resultado de herramientas, designa un nuevo bucle de asistente y todos los bloques de pensamiento anteriores se eliminan del contexto.

Para obtener información más detallada, consulte la documentación de pensamiento extendido.

Almacenamiento en caché y uso compartido

• Aislamiento de Organización: Las cachés se aíslan entre organizaciones. Diferentes organizaciones nunca comparten cachés, incluso si utilizan indicaciones idénticas.

• Coincidencia Exacta: Los aciertos de caché requieren segmentos de indicación 100% idénticos, incluido todo el texto e imágenes hasta e incluyendo el bloque marcado con control de caché.

• Generación de Tokens de Salida: El almacenamiento en caché de indicaciones no tiene efecto en la generación de tokens de salida. La respuesta que reciba será idéntica a la que obtendría si no se utilizara el almacenamiento en caché de indicaciones.

Mejores prácticas para un almacenamiento en caché efectivo

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

• Comience con almacenamiento en caché automático para conversaciones de múltiples turnos. Maneja la gestión de puntos de interrupción automáticamente.
• Utilice puntos de interrupción explícitos a nivel de bloque cuando necesite almacenar en caché diferentes secciones con diferentes frecuencias de cambio.
• Almacene en caché contenido estable y reutilizable como instrucciones del sistema, información de antecedentes, contextos grandes o definiciones de herramientas frecuentes.
• Coloque el contenido almacenado en caché al principio de la indicación para obtener el mejor rendimiento.
• Utilice puntos de interrupción de caché estratégicamente para separar diferentes secciones de prefijo almacenables en caché.
• Coloque el punto de interrupción en el último bloque que permanece idéntico en todas las solicitudes. Para una indicación 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.
• Analice regularmente las tasas de acierto de caché y ajuste su estrategia según sea necesario.

Optimización para diferentes casos de uso

Adapte su estrategia de almacenamiento en caché de indicaciones a su escenario:

• Agentes conversacionales: Reduzca el costo y la latencia para conversaciones extendidas, especialmente aquellas con instrucciones largas o documentos cargados.
• Asistentes de codificación: Mejore el autocompletado y las preguntas y respuestas de base de código manteniendo secciones relevantes o una versión resumida de la base de código en la indicación.
• Procesamiento de documentos grandes: Incorpore material completo de formato largo incluyendo imágenes en su indicación sin aumentar la latencia de respuesta.
• Conjuntos de instrucciones detalladas: Comparta listas extensas de instrucciones, procedimientos y ejemplos para ajustar las respuestas de Claude. Los desarrolladores a menudo incluyen uno o dos ejemplos en la indicación, pero con almacenamiento en caché de indicaciones puede obtener un rendimiento aún mejor incluyendo 20 o más ejemplos diversos de respuestas de alta calidad.
• Uso de herramientas agénticas: Mejore el rendimiento para escenarios que implican múltiples llamadas de herramientas y cambios de código iterativos, donde cada paso típicamente requiere una nueva llamada API.
• Hable con libros, artículos, documentación, transcripciones de podcasts y otro contenido de formato largo: Haga que cualquier base de conocimiento cobre vida incrustando el documento o documentos completos en la indicación y permitiendo que los usuarios le hagan preguntas.

Solución de problemas comunes

Si experimenta un comportamiento inesperado:

• Asegúrese de que las secciones almacenadas en caché sean idénticas en todas las llamadas. Para puntos de interrupción explícitos, verifique que los marcadores cache_control estén en las mismas ubicaciones
• Verifique que las llamadas se realicen dentro de la vida útil de la caché (5 minutos por defecto)
• Verifique que tool_choice y el uso de imágenes permanezcan consistentes entre llamadas
• Valide que esté almacenando en caché al menos el número mínimo de tokens para el modelo que está utilizando (consulte Limitaciones de caché). Los fallos de almacenamiento en caché basados en longitud son silenciosos: la solicitud se realiza correctamente pero tanto cache_creation_input_tokens como cache_read_input_tokens serán 0
• Confirme que su punto de interrupción está en un bloque que permanece idéntico en todas las solicitudes. Las escrituras de 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 de 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
• Verifique que las claves en sus bloques de contenido tengan un orden estable ya que algunos lenguajes (por ejemplo, Swift, Go) aleatorizan el orden de claves durante la conversión JSON, rompiendo cachés

Duración de caché de 1 hora

Si encuentra que 5 minutos es demasiado corto, Anthropic también ofrece una duración de caché de 1 hora con costo adicional.

Para utilizar la caché extendida, incluya ttl en la definición de cache_control así:

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

La respuesta incluirá 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": 456,
      "ephemeral_1h_input_tokens": 100
    }
  }
}

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

Cuándo usar la caché de 1 hora

Si tiene indicaciones que se utilizan en una cadencia regular (es decir, indicaciones del sistema que se utilizan con más frecuencia que cada 5 minutos), continúe utilizando la caché de 5 minutos, ya que esto continuará siendo actualizado sin costo adicional.

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

• Cuando tiene indicaciones que probablemente se utilizan con menos frecuencia que 5 minutos, pero más frecuentemente que cada hora. Por ejemplo, cuando un agente secundario agéntico tardará más de 5 minutos, o cuando almacena una conversación de chat larga con un usuario y generalmente espera que ese usuario no responda en los próximos 5 minutos.
• Cuando la latencia es importante y sus indicaciones de seguimiento pueden enviarse más allá de 5 minutos.
• Cuando desea mejorar su utilización de límite de velocidad, ya que los aciertos de caché no se deducen de su límite de velocidad.

Mezcla de diferentes TTLs

Puede utilizar controles de caché de 1 hora y 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 TTLs más cortas (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 su indicación:

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

Se le 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í hay 3 ejemplos. Esto muestra los tokens de entrada de 3 solicitudes, cada una de las cuales tiene diferentes aciertos de caché y fallos de caché. Cada una tiene un precio calculado diferente, que se muestra en los cuadros de colores, como resultado.

Ejemplos de almacenamiento en caché de prompts

Para ayudarte a comenzar con el almacenamiento en caché de prompts, el libro de recetas 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 característica:

Retención de datos

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

Las representaciones de caché KV (clave-valor) y los hashes criptográficos del contenido en caché se mantienen solo en memoria y no se almacenan en reposo. Las entradas en caché tienen una vida útil mínima de 5 minutos (estándar) o 60 minutos (extendida), después de los cuales se eliminan rápidamente, aunque no inmediatamente. Las entradas en caché están aisladas entre organizaciones.

Para la elegibilidad de ZDR en todas las funciones, consulta API and data retention.

Preguntas frecuentes

Esto es importante para entender tanto costos como límites de velocidad, ya que input_tokens será típicamente mucho más pequeño que tu entrada total cuando uses almacenamiento en caché de manera efectiva.