Almacenamiento en caché de prompts

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-sonnet-4-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
      },
      {
        "type": "text",
        "text": "<the entire contents of Pride and Prejudice>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

# Call the model again with the same inputs up to the cache checkpoint
curl https://api.anthropic.com/v1/messages # rest of input

{"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}

​

Cómo funciona el almacenamiento en caché de prompts

1. El sistema verifica si un prefijo de prompt, 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 el prompt completo y almacena en caché el prefijo una vez que comienza la respuesta.

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

​

Precios

​

Cómo implementar el almacenamiento en caché de prompts

​

Modelos compatibles

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

​

Estructurando tu prompt

​

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

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

​

Cuándo usar múltiples puntos de ruptura

• 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 el almacenamiento en caché para contenido más de 20 bloques antes de tu punto de ruptura final

​

Limitaciones de caché

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

​

Entendiendo los costos de los puntos de ruptura de caché

• Escrituras de caché: Cuando se escribe contenido nuevo 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 regulares: Para cualquier contenido no almacenado en caché

​

Qué se puede almacenar en caché

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

​

Qué no se puede almacenar en caché

• Los bloques de pensamiento no se pueden almacenar 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 del caché.
• Los bloques de subcontenido (como citas) en sí no se pueden almacenar 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 fuente para citas se pueden almacenar en caché. Esto te permite usar el almacenamiento en 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 se pueden almacenar en caché.

​

Qué invalida el caché

​

Rastreando el rendimiento del caché

• 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 del caché ni utilizados para crear un caché.

​

Mejores prácticas para almacenamiento en caché efectivo

• Almacena en caché contenido estable y reutilizable como instrucciones del sistema, información de antecedentes, contextos grandes o definiciones de herramientas frecuentes.
• Coloca contenido almacenado en caché al principio del prompt para mejor rendimiento.
• Usa puntos de ruptura de caché estratégicamente para separar diferentes secciones de prefijo almacenable en caché.
• Analiza regularmente las tasas de acierto de caché y ajusta tu estrategia según sea necesario.

​

Optimizando para diferentes casos de uso

• Agentes conversacionales: Reduce costo y latencia para conversaciones extendidas, especialmente aquellas con instrucciones largas o documentos cargados.
• Asistentes de codificación: Mejora el autocompletado y preguntas y respuestas de 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 forma larga 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 ajustar las respuestas de Claude. Los desarrolladores a menudo incluyen uno o dos ejemplos en el prompt, pero con almacenamiento en caché de prompts puedes obtener un rendimiento aún mejor incluyendo 20+ ejemplos diversos de respuestas de alta calidad.
• Uso de herramientas agéntico: 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.
• Habla con libros, artículos, documentación, transcripciones de podcasts y otro contenido de forma larga: Trae cualquier base de conocimiento a la vida incrustando el documento(s) completo en el prompt, y dejando que los usuarios le hagan preguntas.

​

Solución de problemas comunes

• Asegúrate de que las secciones almacenadas 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 realicen dentro de la vida útil 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 si hay coincidencias de caché en límites de bloques de contenido anteriores (hasta ~20 bloques antes de tu punto de ruptura). Para prompts con más de 20 bloques de contenido, es posible que necesites parámetros cache_control adicionales anteriormente en el prompt para asegurar que todo el contenido se pueda almacenar en caché
• Verifica que las claves en tus bloques de contenido tool_use tengan ordenamiento estable ya que algunos lenguajes (por ejemplo, Swift, Go) aleatorizan el orden de claves durante la conversión JSON, rompiendo cachés

​

Almacenamiento en caché con bloques de pensamiento

• El caché permanece válido cuando solo se proporcionan resultados de herramientas como mensajes de usuario
• El caché se invalida cuando se añade contenido de usuario no relacionado con resultados de herramientas, causando que todos los bloques de pensamiento anteriores se eliminen
• Este comportamiento de almacenamiento en caché ocurre incluso sin marcadores cache_control explícitos

Solicitud 1: Usuario: "¿Cuál es el clima en París?"
Respuesta: [thinking_block_1] + [tool_use block 1]

Solicitud 2:
Usuario: ["¿Cuál es el clima en París?"],
Asistente: [thinking_block_1] + [tool_use block 1],
Usuario: [tool_result_1, cache=True]
Respuesta: [thinking_block_2] + [text block 2]
# La solicitud 2 almacena en caché su contenido de solicitud (no la respuesta)
# El caché incluye: mensaje de usuario, thinking_block_1, tool_use block 1, y tool_result_1

Solicitud 3:
Usuario: ["¿Cuál es el clima en París?"],
Asistente: [thinking_block_1] + [tool_use block 1],
Usuario: [tool_result_1, cache=True],
Asistente: [thinking_block_2] + [text block 2],
Usuario: [Text response, cache=True]
# El bloque de usuario no relacionado con resultados de herramientas causa que todos los bloques de pensamiento se ignoren
# Esta solicitud se procesa como si los bloques de pensamiento nunca estuvieran presentes

​

Almacenamiento y compartición de caché

• Aislamiento de organización: Los cachés se aíslan entre organizaciones. Diferentes organizaciones nunca comparten cachés, incluso si utilizan prompts idénticos.
• Coincidencia exacta: Los aciertos de caché requieren segmentos de prompt 100% idénticos, incluyendo todo el texto e imágenes hasta e incluyendo el bloque marcado con control de caché.
• Generación de tokens de salida: El almacenamiento en caché de prompts no tiene efecto en la generación de tokens de salida. La respuesta que recibas será idéntica a la que obtendrías si el almacenamiento en caché de prompts no se utilizara.

​

Duración de caché de 1 hora

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

{
    "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,
        }
    }
}

​

Cuándo usar el caché de 1 hora

• Cuando tienes prompts que probablemente se usan menos frecuentemente que cada 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 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 deseas mejorar tu utilización de límite de velocidad, ya que los aciertos de caché no se deducen de tu límite de velocidad.

​

Mezclando diferentes TTLs

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.

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).

​

Ejemplos de almacenamiento en caché de prompts

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-sonnet-4-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?"
        }
    ]
}'

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-sonnet-4-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",
                        "description": "The city and state, e.g. San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature, either celsius or fahrenheit"
                    }
                },
                "required": ["location"]
            }
        },
        # many more tools
        {
            "name": "get_time",
            "description": "Get the current time in a given time zone",
            "input_schema": {
                "type": "object",
                "properties": {
                    "timezone": {
                        "type": "string",
                        "description": "The IANA time zone name, e.g. America/Los_Angeles"
                    }
                },
                "required": ["timezone"]
            },
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What is the weather and time in New York?"
        }
    ]
}'

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-sonnet-4-5",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "...long system prompt",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "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 would 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"}
                }
            ]
        }
    ]
}'

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-sonnet-4-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"}
                }
            ]
        }
    ]
}'

​

Preguntas frecuentes

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

python client.messages.create(...)

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

client.messages.create(...)