Caché de prompts

El caché de prompts es una característica poderosa que optimiza el uso de tu API al permitir reanudar desde prefijos específicos en tus prompts. Este enfoque reduce significativamente el tiempo de procesamiento y los costos para tareas repetitivas o prompts con elementos consistentes.

Aquí tienes un ejemplo de cómo implementar el caché de prompts con la API de Messages usando un bloque cache_control:

Shell

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "Eres un asistente de IA encargado de analizar obras literarias. Tu objetivo es proporcionar comentarios perspicaces sobre temas, personajes y estilo de escritura.\n"
      },
      {
        "type": "text",
        "text": "<todo el contenido de Orgullo y Prejuicio>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Analiza los temas principales en Orgullo y Prejuicio."
      }
    ]
  }'

# Llama al modelo nuevamente con las mismas entradas hasta el punto de control del caché
curl https://api.anthropic.com/v1/messages # resto de la entrada

JSON

{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

En este ejemplo, todo el texto de “Orgullo y Prejuicio” se almacena en caché usando el parámetro cache_control. Esto permite reutilizar este texto extenso en múltiples llamadas a la API sin reprocesarlo cada vez. Cambiar solo el mensaje del usuario te permite hacer varias preguntas sobre el libro mientras utilizas el contenido en caché, lo que lleva a respuestas más rápidas y mayor eficiencia.

---

Cómo funciona el caché de prompts

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

1. El sistema verifica si un prefijo de prompt, hasta un punto de interrupción de caché especificado, ya está almacenado en caché desde una consulta reciente.
2. Si se encuentra, utiliza 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

Por defecto, el caché tiene una duración de 5 minutos. El caché se actualiza sin costo adicional cada vez que se utiliza el contenido en caché.

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

Para más información, consulta Duración de caché de 1 hora.

El caché de prompts almacena en caché el prefijo completo

El caché de prompts hace referencia a todo el prompt - tools, system, y messages (en ese orden) hasta e incluyendo el bloque designado con cache_control.

---

Precios

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

Model	Base Input Tokens	5m Cache Writes	1h Cache Writes	Cache Hits & Refreshes	Output Tokens
Claude Opus 4.1	$15 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok	$75 / MTok
Claude Opus 4	$15 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok	$75 / MTok
Claude Sonnet 4	$3 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok	$15 / MTok
Claude Sonnet 3.7	$3 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok	$15 / MTok
Claude Sonnet 3.5 (deprecated)	$3 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok	$15 / MTok
Claude Haiku 3.5	$0.80 / MTok	$1 / MTok	$1.6 / MTok	$0.08 / MTok	$4 / MTok
Claude Opus 3 (deprecated)	$15 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok	$75 / MTok
Claude Haiku 3	$0.25 / MTok	$0.30 / MTok	$0.50 / MTok	$0.03 / MTok	$1.25 / MTok

La tabla anterior refleja los siguientes multiplicadores de precios para el caché de prompts:

• Los tokens de escritura de caché de 5 minutos son 1.25 veces el precio base de tokens de entrada
• Los tokens de escritura de caché de 1 hora son 2 veces el precio base de tokens de entrada
• Los tokens de lectura de caché son 0.1 veces el precio base de tokens de entrada

---

Cómo implementar el caché de prompts

Modelos compatibles

El caché de prompts está actualmente disponible en:

• Claude Opus 4.1
• Claude Opus 4
• Claude Sonnet 4
• Claude Sonnet 3.7
• Claude Sonnet 3.5 (obsoleto)
• Claude Haiku 3.5
• Claude Haiku 3
• Claude Opus 3 (obsoleto)

Estructurando 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 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 basa en 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 coincidente más largo. Así es como funciona:

• Cuando agregas un punto de interrupción cache_control, el sistema verifica automáticamente coincidencias de caché en todos los límites de bloques de contenido anteriores (hasta aproximadamente 20 bloques antes de tu punto de interrupción explícito)
• Si alguna de estas posiciones anteriores coincide con contenido en caché de solicitudes anteriores, el sistema usa el prefijo coincidente más largo
• Esto significa que no necesitas múltiples puntos de interrupción solo para habilitar el caché - uno al final es suficiente

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 el caché para contenido que está más de 20 bloques antes de tu punto de interrupción final

Limitación importante: La verificación automática de prefijos solo mira hacia atrás aproximadamente 20 bloques de contenido desde cada punto de interrupción explícito. Si tu prompt tiene más de 20 bloques de contenido antes de tu punto de interrupción de caché, el contenido anterior a eso no será verificado para coincidencias de caché a menos que agregues puntos de interrupción adicionales.

Limitaciones del caché

La longitud mínima de prompt almacenable en caché es:

• 1024 tokens para Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 (obsoleto) y Claude Opus 3 (obsoleto)
• 2048 tokens para Claude Haiku 3.5 y Claude Haiku 3

Los prompts más cortos no pueden almacenarse en caché, incluso si están marcados con cache_control. Cualquier solicitud para almacenar en caché menos de este número de tokens será procesada sin caché. Para ver si un prompt fue almacenado en caché, consulta los campos de uso de la respuesta.

Para solicitudes concurrentes, ten en cuenta que una entrada de caché solo se vuelve disponible después de que comience la primera respuesta. Si necesitas coincidencias de caché para solicitudes paralelas, espera la primera respuesta antes de enviar solicitudes posteriores.

Actualmente, “ephemeral” es el único tipo de caché compatible, que por defecto tiene una duración de 5 minutos.

Entendiendo 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 de caché: Cuando se escribe nuevo contenido al caché (25% más que los tokens de entrada base para TTL de 5 minutos)
• Lecturas de caché: Cuando se utiliza contenido en caché (10% del precio de token de entrada base)
• 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 basada en qué contenido se almacena realmente en caché y se lee. Los puntos de interrupción simplemente te dan control sobre qué secciones pueden almacenarse en caché independientemente.

Qué se puede almacenar en caché

La mayoría de los bloques en la solicitud pueden designarse para caché con cache_control. 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 tanto 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, en turnos tanto de usuario como de asistente

Cada uno de estos elementos puede marcarse con cache_control para habilitar el caché para esa porción de la solicitud.

Qué no se puede almacenar en caché

Aunque la mayoría de los 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 SÍ 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 sub-bloques de contenido (como citas) en sí mismos no pueden almacenarse 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 pueden almacenarse en caché. Esto te permite usar el caché de prompts con citas de manera efectiva almacenando en caché los documentos que las citas referenciarán.

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

Qué invalida el caché

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

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

La siguiente tabla muestra qué partes del caché son invalidadas por diferentes tipos de cambios. ✘ indica que el caché es invalidado, mientras que ✓ indica que el caché permanece válido.

Qué cambia	Caché de herramientas	Caché del sistema	Caché de mensajes	Impacto
Definiciones de herramientas	✘	✘	✘	Modificar definiciones de herramientas (nombres, descripciones, parámetros) invalida todo el caché
Alternar búsqueda web	✓	✘	✘	Habilitar/deshabilitar la búsqueda web modifica el prompt del sistema
Alternar citas	✓	✘	✘	Habilitar/deshabilitar citas modifica el prompt del sistema
Elección de herramienta	✓	✓	✘	Los cambios al parámetro tool_choice solo afectan los bloques de mensajes
Imágenes	✓	✓	✘	Agregar/quitar imágenes en cualquier lugar del prompt afecta los bloques de mensajes
Parámetros de pensamiento	✓	✓	✘	Los cambios en la configuración de pensamiento extendido (habilitar/deshabilitar, presupuesto) afectan los bloques de mensajes
Resultados no-herramienta pasados a solicitudes de pensamiento extendido	✓	✓	✘	Cuando se pasan resultados no-herramienta en solicitudes mientras el pensamiento extendido está habilitado, todos los bloques de pensamiento previamente almacenados en caché se eliminan del contexto, y cualquier mensaje en contexto que siga a esos bloques de pensamiento se elimina del caché. Para más detalles, consulta Caché con bloques de pensamiento.

Seguimiento del rendimiento del caché

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

• cache_creation_input_tokens: Número de tokens escritos al 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 desde o usados para crear un caché.

Mejores prácticas para un caché efectivo

Para optimizar el rendimiento del caché de prompts:

• 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 el mejor rendimiento.
• Usa puntos de interrupción de caché estratégicamente para separar diferentes secciones de prefijo almacenables en caché.
• Analiza regularmente las tasas de acierto de caché y ajusta tu estrategia según sea necesario.

Optimizando para diferentes casos de uso

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

• Agentes conversacionales: Reduce el costo y la latencia para conversaciones extendidas, especialmente aquellas con instrucciones largas o documentos subidos.
• Asistentes de codificación: Mejora el autocompletado y las preguntas y respuestas de la base 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 un ejemplo o dos en el prompt, pero con el 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énticas: Mejora el rendimiento para escenarios que involucran múltiples llamadas de herramientas y cambios de código iterativos, donde cada paso típicamente requiere una nueva llamada a la API.
• Hablar con libros, artículos, documentación, transcripciones de podcasts y otro contenido de formato largo: Da vida a cualquier base de conocimiento incrustando todo el documento(s) en el prompt, y permitiendo a los usuarios hacerle preguntas.

Solución de problemas comunes

Si experimentas comportamiento inesperado:

• Asegúrate de que las secciones en caché sean idénticas y estén marcadas con cache_control en las mismas ubicaciones en todas las llamadas
• Verifica que las llamadas se hagan dentro de la duración del caché (5 minutos por defecto)
• Verifica que tool_choice y el uso de imágenes permanezcan consistentes entre llamadas
• Valida que estés almacenando en caché al menos el número mínimo de tokens
• El sistema verifica automáticamente coincidencias de caché en límites de bloques de contenido anteriores (hasta ~20 bloques antes de tu punto de interrupción). Para prompts con más de 20 bloques de contenido, podrías necesitar parámetros cache_control adicionales más temprano en el prompt para asegurar que todo el contenido pueda almacenarse en caché

Los cambios a tool_choice o la presencia/ausencia de imágenes en cualquier lugar del prompt invalidarán el caché, requiriendo que se cree una nueva entrada de caché. Para más detalles sobre la invalidación del caché, consulta Qué invalida el caché.

Caché con bloques de pensamiento

Cuando uses pensamiento extendido con caché de prompts, los bloques de pensamiento tienen un comportamiento especial:

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 haces llamadas subsiguientes a la API con resultados de herramientas. Esto comúnmente sucede 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 desde el caché, cuentan como tokens de entrada en tus métricas de uso. Esto es importante para el cálculo de costos y el presupuesto de tokens.

Patrones de invalidación de caché:

• El caché permanece válido cuando solo se proporcionan resultados de herramientas como mensajes de usuario
• El caché se invalida cuando se agrega contenido de usuario que no es resultado de herrami

Ejemplo con uso de herramientas:

Solicitud 1: Usuario: "¿Cuál es el clima en París?"
Respuesta: [bloque_pensamiento_1] + [bloque uso herramienta 1]

Solicitud 2: 
Usuario: ["¿Cuál es el clima en París?"], 
Asistente: [bloque_pensamiento_1] + [bloque uso herramienta 1], 
Usuario: [resultado_herramienta_1, cache=True]
Respuesta: [bloque_pensamiento_2] + [bloque texto 2]
# La Solicitud 2 almacena en caché su contenido de solicitud (no la respuesta)
# El caché incluye: mensaje de usuario, bloque_pensamiento_1, bloque uso herramienta 1, y resultado_herramienta_1

Solicitud 3:
Usuario: ["¿Cuál es el clima en París?"], 
Asistente: [bloque_pensamiento_1] + [bloque uso herramienta 1], 
Usuario: [resultado_herramienta_1, cache=True], 
Asistente: [bloque_pensamiento_2] + [bloque texto 2], 
Usuario: [Respuesta de texto, cache=True]
# El bloque de usuario que no es resultado de herramienta causa que todos los bloques de pensamiento sean ignorados
# Esta solicitud se procesa como si los bloques de pensamiento nunca hubieran estado presentes

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

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

---

Almacenamiento y compartición de caché

• Aislamiento de Organización: Los cachés están aislados entre organizaciones. Diferentes organizaciones nunca comparten cachés, incluso si usan prompts idénticos.

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

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

---

Duración de caché de 1 hora

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

Para usar el caché extendido, incluye ttl en la definición cache_control así:

"cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
}

La respuesta incluirá información detallada del caché como la siguiente:

{
    "usage": {
        "input_tokens": ...,
        "cache_read_input_tokens": ...,
        "cache_creation_input_tokens": ...,
        "output_tokens": ...,
        
        "cache_creation": {
            "ephemeral_5m_input_tokens": 456,
            "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.

Cuándo usar el caché de 1 hora

Si tienes prompts que se usan con una cadencia regular (es decir, prompts del sistema que se usan más frecuentemente que cada 5 minutos), continúa usando el caché de 5 minutos, ya que este continuará actualizándose sin cargo adicional.

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

• Cuando tienes prompts que probablemente se usan menos frecuentemente que 5 minutos, pero más frecuentemente que cada hora. Por ejemplo, cuando un agente lateral agéntico tomará 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 más allá de 5 minutos.
• Cuando quieres mejorar la utilización de tu límite de tasa, ya que las coincidencias de caché no se deducen de tu límite de tasa.

El caché de 5 minutos y 1 hora se comportan igual con respecto a la latencia. Generalmente verás un tiempo mejorado hasta el primer token para documentos largos.

Mezclando diferentes TTLs

Puedes usar controles de caché tanto de 1 hora como 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 TTLs más cortos (es decir, una entrada de caché de 1 hora debe aparecer antes que cualquier entrada de caché de 5 minutos).

Cuando mezclas TTLs, determinamos tres ubicaciones de facturación en tu prompt:

1. Posición A: El conteo de tokens en la coincidencia de caché más alta (o 0 si no hay coincidencias).
2. Posición B: El conteo 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 conteo de tokens en el último bloque cache_control.

Si B y/o C son mayores que A, necesariamente serán fallos de caché, porque A es la coincidencia de caché más alta.

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í hay 3 ejemplos. Esto representa los tokens de entrada de 3 solicitudes, cada una de las cuales tiene diferentes coincidencias y fallos de caché. Cada una tiene un precio calculado diferente, mostrado en las cajas de colores, como resultado.

---

Ejemplos de caché de prompts

Para ayudarte a comenzar con el caché de prompts, hemos preparado un libro de cocina de caché de prompts con ejemplos detallados y mejores prácticas.

A continuación, hemos incluido varios fragmentos de código que muestran varios patrones de caché de prompts. Estos ejemplos demuestran cómo implementar el caché en diferentes escenarios, ayudándote a entender las aplicaciones prácticas de esta característica:

Ejemplo de caché de contexto grande

Shell

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "Eres un asistente de IA encargado de analizar documentos legales."
        },
        {
            "type": "text",
            "text": "Aquí está el texto completo de un acuerdo legal complejo: [Insertar texto completo de un acuerdo legal de 50 páginas aquí]",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "¿Cuáles son los términos y condiciones clave en este acuerdo?"
        }
    ]
}'

Este ejemplo demuestra el uso básico del caché de prompts, almacenando en caché el texto completo del acuerdo legal como un prefijo mientras mantiene la instrucción del usuario sin caché.

Para la primera solicitud:

• input_tokens: Número de tokens solo en el mensaje del usuario
• cache_creation_input_tokens: Número de tokens en todo el mensaje del sistema, incluyendo el documento legal
• cache_read_input_tokens: 0 (sin coincidencia de caché en la primera solicitud)

Para solicitudes subsiguientes dentro de la duración del caché:

• input_tokens: Número de tokens solo en el mensaje del usuario
• cache_creation_input_tokens: 0 (sin nueva creación de caché)
• cache_read_input_tokens: Número de tokens en todo el mensaje del sistema en caché

Almacenando en caché definiciones de herramientas

Shell

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Obtener el clima actual en una ubicación dada",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "La ciudad y estado, ej. San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "La unidad de temperatura, ya sea celsius o fahrenheit"
                    }
                },
                "required": ["location"]
            }
        },
        # muchas más herramientas
        {
            "name": "get_time",
            "description": "Obtener la hora actual en una zona horaria dada",
            "input_schema": {
                "type": "object",
                "properties": {
                    "timezone": {
                        "type": "string",
                        "description": "El nombre de zona horaria IANA, ej. America/Los_Angeles"
                    }
                },
                "required": ["timezone"]
            },
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "¿Cuál es el clima y la hora en Nueva York?"
        }
    ]
}'

En este ejemplo, demostramos el almacenamiento en caché de definiciones de herramientas.

El parámetro cache_control se coloca en la herramienta final (get_time) para designar todas las herramientas como parte del prefijo estático.

Esto significa que todas las definiciones de herramientas, incluyendo get_weather y cualquier otra herramienta definida antes de get_time, se almacenarán en caché como un solo prefijo.

Este enfoque es útil cuando tienes un conjunto consistente de herramientas que quieres reutilizar en múltiples solicitudes sin reprocesarlas cada vez.

Para la primera solicitud:

• input_tokens: Número de tokens en el mensaje del usuario
• cache_creation_input_tokens: Número de tokens en todas las definiciones de herramientas y prompt del sistema
• cache_read_input_tokens: 0 (sin coincidencia de caché en la primera solicitud)

Para solicitudes subsiguientes dentro de la duración del caché:

• input_tokens: Número de tokens en el mensaje del usuario
• cache_creation_input_tokens: 0 (sin nueva creación de caché)
• cache_read_input_tokens: Número de tokens en todas las definiciones de herramientas en caché y prompt del sistema

Continuando una conversación de múltiples turnos

Shell

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "...prompt del sistema largo",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Hola, ¿puedes contarme más sobre el sistema solar?",
                }
            ]
        },
        {
            "role": "assistant",
            "content": "¡Por supuesto! El sistema solar es la colección de cuerpos celestes que orbitan nuestro Sol. Consiste en ocho planetas, numerosas lunas, asteroides, cometas y otros objetos. Los planetas, en orden desde el más cercano al más lejano del Sol, son: Mercurio, Venus, Tierra, Marte, Júpiter, Saturno, Urano y Neptuno. Cada planeta tiene sus propias características y características únicas. ¿Hay algún aspecto específico del sistema solar sobre el que te gustaría saber más?"
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Bueno saberlo."
                },
                {
                    "type": "text",
                    "text": "Cuéntame más sobre Marte.",
                    "cache_control": {"type": "ephemeral"}
                }
            ]
        }
    ]
}'

En este ejemplo, demostramos cómo usar el caché de prompts en una conversación de múltiples turnos.

Durante cada turno, marcamos el bloque final del mensaje final con cache_control para que la conversación pueda almacenarse en caché incrementalmente. El sistema buscará automáticamente y usará el prefijo previamente almacenado en caché más largo para mensajes de seguimiento. Es decir, los bloques que fueron previamente marcados con un bloque cache_control más tarde no están marcados con esto, pero aún se considerarán una coincidencia de caché (¡y también una actualización de caché!) si se encuentran dentro de 5 minutos.

Además, nota que el parámetro cache_control se coloca en el mensaje del sistema. Esto es para asegurar que si esto se desaloja del caché (después de no usarse por más de 5 minutos), se agregará de vuelta al caché en la siguiente solicitud.

Este enfoque es útil para mantener el contexto en conversaciones en curso sin procesar repetidamente la misma información.

Cuando esto se configura correctamente, deberías ver lo siguiente en la respuesta de uso de cada solicitud:

• input_tokens: Número de tokens en el nuevo mensaje de usuario (será mínimo)
• cache_creation_input_tokens: Número de tokens en los nuevos turnos de asistente y usuario
• cache_read_input_tokens: Número de tokens en la conversación hasta el turno anterior

Juntándolo todo: Múltiples puntos de interrupción de caché

Shell

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "search_documents",
            "description": "Buscar a través de la base de conocimiento",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Consulta de búsqueda"
                    }
                },
                "required": ["query"]
            }
        },
        {
            "name": "get_document",
            "description": "Recuperar un documento específico por ID",
            "input_schema": {
                "type": "object",
                "properties": {
                    "doc_id": {
                        "type": "string",
                        "description": "ID del documento"
                    }
                },
                "required": ["doc_id"]
            },
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "system": [
        {
            "type": "text",
            "text": "Eres un asistente de investigación útil con acceso a una base de conocimiento de documentos.\n\n# Instrucciones\n- Siempre busca documentos relevantes antes de responder\n- Proporciona citas para tus fuentes\n- Sé objetivo y preciso en tus respuestas\n- Si múltiples documentos contienen información relevante, sintetízalos\n- Reconoce cuando la información no está disponible en la base de conocimiento",
            "cache_control": {"type": "ephemeral"}
        },
        {
            "type": "text",
            "text": "# Contexto de Base de Conocimiento\n\nAquí están los documentos relevantes para esta conversación:\n\n## Documento 1: Resumen del Sistema Solar\nEl sistema solar consiste en el Sol y todos los objetos que lo orbitan...\n\n## Documento 2: Características Planetarias\nCada planeta tiene características únicas. Mercurio es el planeta más pequeño...\n\n## Documento 3: Exploración de Marte\nMarte ha sido un objetivo de exploración durante décadas...\n\n[Documentos adicionales...]",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "¿Puedes buscar información sobre rovers de Marte?"
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "tool_use",
                    "id": "tool_1",
                    "name": "search_documents",
                    "input": {"query": "rovers de Marte"}
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "tool_1",
                    "content": "Se encontraron 3 documentos relevantes: Documento 3 (Exploración de Marte), Documento 7 (Tecnología de Rovers), Documento 9 (Historia de Misiones)"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "Encontré 3 documentos relevantes sobre rovers de Marte. Déjame obtener más detalles del documento de Exploración de Marte."
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Sí, por favor cuéntame sobre el rover Perseverance específicamente.",
                    "cache_control": {"type": "ephemeral"}
                }
            ]
        }
    ]
}'

Este ejemplo integral demuestra cómo usar los 4 puntos de interrupción de caché disponibles para optimizar diferentes partes de tu prompt:

1. Caché de herramientas (punto de interrupción de caché 1): El parámetro cache_control en la última definición de herramienta almacena en caché todas las definiciones de herramientas.

2. Caché de instrucciones reutilizables (punto de interrupción de caché 2): Las instrucciones estáticas en el prompt del sistema se almacenan en caché por separado. Estas instrucciones rara vez cambian entre solicitudes.

3. Caché de contexto RAG (punto de interrupción de caché 3): Los documentos de la base de conocimiento se almacenan en caché independientemente, permitiéndote actualizar los documentos RAG sin invalidar el caché de herramientas o instrucciones.

4. Caché de historial de conversación (punto de interrupción de caché 4): La respuesta del asistente está marcada con cache_control para habilitar el caché incremental de la conversación a medida que progresa.

Este enfoque proporciona máxima flexibilidad:

• Si solo actualizas el mensaje final del usuario, los cuatro segmentos de caché se reutilizan
• Si actualizas los documentos RAG pero mantienes las mismas herramientas e instrucciones, los primeros dos segmentos de caché se reutilizan
• Si cambias la conversación pero mantienes las mismas herramientas, instrucciones y documentos, los primeros tres segmentos se reutilizan
• Cada punto de interrupción de caché puede invalidarse independientemente basado en qué cambia en tu aplicación

Para la primera solicitud:

• input_tokens: Tokens en el mensaje final del usuario
• cache_creation_input_tokens: Tokens en todos los segmentos en caché (herramientas + instrucciones + documentos RAG + historial de conversación)
• cache_read_input_tokens: 0 (sin coincidencias de caché)

Para solicitudes subsiguientes con solo un nuevo mensaje de usuario:

• input_tokens: Tokens solo en el nuevo mensaje de usuario
• cache_creation_input_tokens: Cualquier nuevo token agregado al historial de conversación
• cache_read_input_tokens: Todos los tokens previamente almacenados en caché (herramientas + instrucciones + documentos RAG + conversación anterior)

Este patrón es especialmente poderoso para:

• Aplicaciones RAG con contextos de documentos grandes
• Sistemas de agentes que usan múltiples herramientas
• Conversaciones de larga duración que necesitan mantener contexto
• Aplicaciones que necesitan optimizar diferentes partes del prompt independientemente

---

FAQ

¿Necesito múltiples puntos de interrupción de caché o es suficiente uno al final?

En la mayoría de los casos, un solo punto de interrupción de caché al final de tu contenido estático es suficiente. El sistema verifica automáticamente coincidencias de caché en todos los límites de bloques de contenido anteriores (hasta 20 bloques antes de tu punto de interrupción) y usa el prefijo coincidente más largo.

Solo necesitas múltiples puntos de interrupción si:

• Tienes más de 20 bloques de contenido antes de tu punto de caché deseado
• Quieres almacenar en caché secciones que se actualizan con diferentes frecuencias independientemente
• Necesitas control explícito sobre qué se almacena en caché para optimización de costos

Ejemplo: Si tienes instrucciones del sistema (rara vez cambian) y contexto RAG (cambia diariamente), podrías usar dos puntos de interrupción para almacenarlos en caché por separado.

¿Los puntos de interrupción de caché agregan costo extra?

No, los puntos de interrupción de caché en sí mismos son gratuitos. Solo pagas por:

• Escribir contenido al caché (25% más que los tokens de entrada base para TTL de 5 minutos)
• Leer desde el caché (10% del precio de token de entrada base)
• Tokens de entrada regulares para contenido no almacenado en caché

El número de puntos de interrupción no afecta el precio - solo importa la cantidad de contenido almacenado en caché y leído.

¿Cuál es la duración del caché?

La duración mínima por defecto del caché (TTL) es de 5 minutos. Esta duración se actualiza cada vez que se usa el contenido en caché.

Si encuentras que 5 minutos es demasiado corto, Anthropic también ofrece un TTL de caché de 1 hora.

¿Cuántos puntos de interrupción de caché puedo usar?

Puedes definir hasta 4 puntos de interrupción de caché (usando parámetros cache_control) en tu prompt.

¿Está disponible el caché de prompts para todos los modelos?

No, el caché de prompts está actualmente disponible solo para Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 (obsoleto), Claude Haiku 3.5, Claude Haiku 3, y Claude Opus 3 (obsoleto).

¿Cómo funciona el caché de prompts con pensamiento extendido?

Los prompts del sistema y herramientas en caché se reutilizarán cuando cambien los parámetros de pensamiento. Sin embargo, los cambios de pensamiento (habilitar/deshabilitar o cambios de presupuesto) invalidarán prefijos de prompt previamente almacenados en caché con contenido de mensajes.

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

Para más sobre pensamiento extendido, incluyendo su interacción con uso de herramientas y caché de prompts, consulta la documentación de pensamiento extendido.

¿Cómo habilito el caché de prompts?

Para habilitar el caché de prompts, incluye al menos un punto de interrupción cache_control en tu solicitud de API.

¿Puedo usar el caché de prompts con otras características de la API?

Sí, el caché de prompts puede usarse junto con otras características de la API como uso de herramientas y capacidades de visión. Sin embargo, cambiar si hay imágenes en un prompt o modificar configuraciones de uso de herramientas romperá el caché.

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

¿Cómo afecta el caché de prompts a los precios?

El caché de prompts introduce una nueva estructura de precios donde las escrituras de caché cuestan 25% más que los tokens de entrada base, mientras que las coincidencias de caché cuestan solo 10% del precio de token de entrada base.

¿Puedo limpiar manualmente el caché?

Actualmente, no hay forma de limpiar manualmente el caché. Los prefijos en caché expiran automáticamente después de un mínimo de 5 minutos de inactividad.

¿Cómo puedo rastrear la efectividad de mi estrategia de caché?

Puedes monitorear el rendimiento del caché usando los campos cache_creation_input_tokens y cache_read_input_tokens en la respuesta de la API.

¿Qué puede romper el caché?

Consulta Qué invalida el caché para más detalles sobre invalidación de caché, incluyendo una lista de cambios que requieren crear una nueva entrada de caché.

¿Cómo maneja el caché de prompts la privacidad y separación de datos?

El caché de prompts está diseñado con fuertes medidas de privacidad y separación de datos:

1. Las claves de caché se generan usando un hash criptográfico de los prompts hasta el punto de control de caché. Esto significa que solo las solicitudes con prompts idénticos pueden acceder a un caché específico.

2. Los cachés son específicos de la organización. Los usuarios dentro de la misma organización pueden acceder al mismo caché si usan prompts idénticos, pero los cachés no se comparten entre diferentes organizaciones, incluso para prompts idénticos.

3. El mecanismo de caché está diseñado para mantener la integridad y privacidad de cada conversación o contexto único.

4. Es seguro usar cache_control en cualquier lugar de tus prompts. Para eficiencia de costos, es mejor excluir partes altamente variables (ej., entrada arbitraria del usuario) del caché.

Estas medidas aseguran que el caché de prompts mantenga la privacidad y seguridad de los datos mientras ofrece beneficios de rendimiento.

¿Puedo usar el caché de prompts con la API de Lotes?

Sí, es posible usar el caché de prompts con tus solicitudes de API de Lotes. Sin embargo, debido a que las solicitudes de lotes asíncronas pueden procesarse concurrentemente y en cualquier orden, las coincidencias de caché se proporcionan en base al mejor esfuerzo.

El caché de 1 hora puede ayudar a mejorar tus coincidencias de caché. La forma más rentable de usarlo es la siguiente:

• Reúne un conjunto de solicitudes de mensajes que tienen un prefijo compartido.
• Envía una solicitud de lote con solo una solicitud que tenga este prefijo compartido y un bloque de caché de 1 hora. Esto se escribirá al caché de 1 hora.
• Tan pronto como esto se complete, envía el resto de las solicitudes. Tendrás que monitorear el trabajo para saber cuándo se completa.

Esto es típicamente mejor que usar el caché de 5 minutos simplemente porque es común que las solicitudes de lotes tomen entre 5 minutos y 1 hora para completarse. Estamos considerando formas de mejorar estas tasas de coincidencia de caché y hacer este proceso más directo.

¿Por qué veo el error `AttributeError: 'Beta' object has no attribute 'prompt_caching'` en Python?

Este error típicamente aparece cuando has actualizado tu SDK o estás usando ejemplos de código desactualizados. El caché de prompts ahora está generalmente disponible, por lo que ya no necesitas el prefijo beta. En lugar de:

Python

python client.beta.prompt_caching.messages.create(...)

Simplemente usa:

Python

python client.messages.create(...)

¿Por qué veo 'TypeError: Cannot read properties of undefined (reading 'messages')'?

Este error típicamente aparece cuando has actualizado tu SDK o estás usando ejemplos de código desactualizados. El caché de prompts ahora está generalmente disponible, por lo que ya no necesitas el prefijo beta. En lugar de:

TypeScript

client.beta.promptCaching.messages.create(...)

Simplemente usa:

client.messages.create(...)