Almacenamiento en caché de prompts

El almacenamiento en caché de prompts es una característica poderosa que optimiza el uso de tu API permitiendo 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í hay un ejemplo de cómo implementar el almacenamiento en caché de prompts con la API de Mensajes usando un bloque cache_control:

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

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    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'."}],
)
print(response.usage.model_dump_json())

# Call the model again with the same inputs up to the cache checkpoint
response = client.messages.create(.....)
print(response.usage.model_dump_json())

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

const response = await client.messages.create({
  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'."
    }
  ]
});
console.log(response.usage);

// Call the model again with the same inputs up to the cache checkpoint
const new_response = await client.messages.create(...)
console.log(new_response.usage);

import java.util.List;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.CacheControlEphemeral;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.TextBlockParam;

public class PromptCachingExample {

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        MessageCreateParams params = MessageCreateParams.builder()
                .model(Model.CLAUDE_OPUS_4_20250514)
                .maxTokens(1024)
                .systemOfTextBlockParams(List.of(
                        TextBlockParam.builder()
 .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")
 .build(),
                        TextBlockParam.builder()
 .text("<the entire contents of 'Pride and Prejudice'>")
 .cacheControl(CacheControlEphemeral.builder().build())
 .build()
                ))
                .addUserMessage("Analyze the major themes in 'Pride and Prejudice'.")
                .build();

        Message message = client.messages().create(params);
        System.out.println(message.usage());
    }
}

{"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 "Pride and Prejudice" se almacena en caché usando el parámetro cache_control. Esto permite reutilizar este texto grande 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 almacenado en caché, lo que resulta en respuestas más rápidas y mayor eficiencia.

Cómo funciona el almacenamiento en caché de prompts

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

1. El sistema verifica si un prefijo 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.

Esto es especialmente útil para:

• Prompts 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 prompts introduce una nueva estructura de precios. La tabla a continuación muestra el precio por millón de tokens para cada modelo compatible:

Cómo implementar el almacenamiento en caché de prompts

Modelos compatibles

El almacenamiento en caché de prompts es actualmente compatible con:

• 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 (deprecated)

Estructurando tu prompt

Coloca contenido estático (definiciones de herramientas, instrucciones del sistema, contexto, ejemplos) al principio de tu prompt. 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 coincidente más largo. Entender cómo funciona esto te ayuda a optimizar tu estrategia de almacenamiento en caché.

Tres principios principales:

1. Las claves de caché son acumulativas: Cuando almacenas explícitamente un bloque con cache_control, la clave hash de caché se genera hasheando todos los bloques anteriores en la conversación secuencialmente. Esto significa que el caché para cada bloque depende de todo el contenido que vino antes.

2. Verificación secuencial hacia atrás: El sistema verifica si hay aciertos de caché trabajando hacia atrás desde tu punto de ruptura explícito, verificando cada bloque anterior en orden inverso. Esto asegura que obtengas el acierto de caché más largo posible.

3. Ventana de búsqueda retrospectiva de 20 bloques: El sistema solo verifica hasta 20 bloques antes de cada punto de ruptura cache_control explícito. Después de verificar 20 bloques sin encontrar una coincidencia, deja de verificar y pasa al siguiente punto de ruptura explícito (si existe).

Ejemplo: Entendiendo la ventana de búsqueda retrospectiva

Considera una conversación con 30 bloques de contenido donde estableces cache_control solo en el bloque 30:

• Si envías el bloque 31 sin cambios en bloques anteriores: El sistema verifica el bloque 30 (¡coincidencia!). Obtienes un acierto de caché en el bloque 30, y solo el bloque 31 necesita procesamiento.

• Si modificas el bloque 25 y envías el bloque 31: El sistema verifica hacia atrás desde el bloque 30 → 29 → 28... → 25 (sin coincidencia) → 24 (¡coincidencia!). Como el bloque 24 no ha cambiado, obtienes un acierto de caché en el bloque 24, y solo los bloques 25-30 necesitan reprocesamiento.

• Si modificas el bloque 5 y envías el bloque 31: El sistema verifica hacia atrás desde el bloque 30 → 29 → 28... → 11 (verificación #20). Después de 20 verificaciones sin encontrar una coincidencia, deja de buscar. Como el bloque 5 está más allá de la ventana de 20 bloques, no hay acierto de caché y todos los bloques necesitan reprocesamiento. Sin embargo, si hubieras establecido un punto de ruptura cache_control explícito en el bloque 5, el sistema continuaría verificando desde ese punto de ruptura: bloque 5 (sin coincidencia) → bloque 4 (¡coincidencia!). Esto permite un acierto de caché en el bloque 4, demostrando por qué debes colocar puntos de ruptura antes del contenido editable.

Conclusión clave: Siempre establece un punto de ruptura de caché explícito al final de tu conversación para maximizar tus posibilidades de aciertos de caché. Además, establece puntos de ruptura justo antes de bloques de contenido que podrían ser editables para asegurar que esas secciones se puedan almacenar en caché de forma independiente.

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 almacenamiento en caché para contenido más de 20 bloques antes de tu punto de ruptura final
• Colocar puntos de ruptura antes del contenido editable para garantizar aciertos de caché incluso cuando ocurren cambios más allá de la ventana de 20 bloques

Limitaciones de caché

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

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

Los prompts más cortos no se pueden almacenar 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é. Para ver si un prompt fue almacenado en caché, consulta los campos de uso de respuesta.

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

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

Entendiendo los costos de los puntos de ruptura de caché

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

• 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é

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

Qué se puede almacenar en caché

La mayoría de bloques en la solicitud se pueden designar para almacenamiento en 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 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 se puede marcar con cache_control para habilitar el almacenamiento en caché para esa parte de la solicitud.

Qué no se puede almacenar en caché

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

• Los bloques de pensamiento no se pueden almacenar en caché directamente con cache_control. Sin embargo, los bloques de pensamiento PUEDEN almacenarse en caché junto con otro contenido cuando aparecen en turnos anteriores del asistente. Cuando se almacenan en caché de esta manera, SÍ cuentan como tokens de entrada cuando se leen 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 referenciaran.

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

Qué invalida el caché

Las modificaciones al contenido almacenado 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 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.

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

Mejores prácticas para almacenamiento en caché efectivo

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

• 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é.
• Establece puntos de ruptura de caché al final de conversaciones y justo antes del contenido editable para maximizar las tasas de acierto de caché, especialmente cuando se trabaja con prompts que tienen más de 20 bloques de contenido.
• 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 almacenamiento en caché de prompts a tu escenario:

• Agentes conversacionales: Reduce costo y latencia para conversaciones extendidas, especialmente aquellas con instrucciones largas o documentos cargados.
• Asistentes de codificación: Mejora 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 de agentes: 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: Dale vida a cualquier base de conocimiento incrustando el documento(s) completo en el prompt, y permitiendo que los usuarios le hagan preguntas.

Solución de problemas comunes

Si experimentas comportamiento inesperado:

• Asegúrate de que las secciones almacenadas en caché sean idénticas y 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 aciertos 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

Cuando usas pensamiento extendido con almacenamiento en caché de prompts, los bloques de pensamiento tienen comportamiento especial:

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

Conteo de tokens de entrada: Cuando los bloques de pensamiento se leen del caché, cuentan como tokens de entrada en tus métricas de uso. Esto es importante para el cálculo de costos y 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 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

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

Ejemplo con uso de herramientas:

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 hubieran estado presentes

Cuando se incluye un bloque de usuario no relacionado con resultados de herramientas, 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 se aíslan entre organizaciones. Diferentes organizaciones nunca comparten cachés, incluso si usan 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 usara.

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 con costo adicional.

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 de caché detallada 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 cache_creation_input_tokens actual 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 a 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 esto continuará siendo actualizado sin costo adicional.

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

• 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 de agentes 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

Puedes usar 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 de TTLs más cortos (es decir, una entrada de caché de 1 hora debe aparecer antes de 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 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 no existen).
3. Posición C: El conteo de tokens en el último bloque cache_control.

Se te cobrará por:

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

Aquí hay 3 ejemplos. Esto muestra los tokens de entrada de 3 solicitudes, cada una con diferentes aciertos de caché y fallos de caché. Cada una tiene una facturación diferente calculada, mostrada en los cuadros de color, como resultado.

Ejemplos de almacenamiento en caché de prompts

Para ayudarte a comenzar con el almacenamiento en caché de prompts, hemos preparado un libro de recetas de almacenamiento en 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 almacenamiento en caché de prompts. Estos ejemplos demuestran cómo implementar almacenamiento en caché en diferentes escenarios, ayudándote a entender las aplicaciones prácticas de esta característica:

Preguntas frecuentes