El almacenamiento en caché de indicaciones es una característica poderosa que optimiza el uso de tu API permitiendo reanudar desde prefijos específicos en tus indicaciones. Este enfoque reduce significativamente el tiempo de procesamiento y los costos para tareas repetitivas o indicaciones con elementos consistentes.
Aquí hay un ejemplo de cómo implementar el almacenamiento en caché de indicaciones 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{"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 una eficiencia mejorada.
El almacenamiento en caché de indicaciones es una característica poderosa que optimiza el uso de tu API permitiendo reanudar desde prefijos específicos en tus indicaciones. Este enfoque reduce significativamente el tiempo de procesamiento y los costos para tareas repetitivas o indicaciones con elementos consistentes.
Aquí hay un ejemplo de cómo implementar el almacenamiento en caché de indicaciones 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{"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 una eficiencia mejorada.
Cuando envías una solicitud con el almacenamiento en caché de indicaciones habilitado:
Esto es especialmente útil para:
De forma predeterminada, 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é.
Si encuentras que 5 minutos es demasiado corto, Anthropic también ofrece una duración de caché de 1 hora con costo adicional.
Para más información, consulta duración de caché de 1 hora.
El almacenamiento en caché de indicaciones almacena en caché el prefijo completo
El almacenamiento en caché de indicaciones hace referencia a la indicación completa - tools, system, y messages (en ese orden) hasta e incluyendo el bloque designado con cache_control.
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 compatible:
| Model | Base Input Tokens | 5m Cache Writes | 1h Cache Writes | Cache Hits & Refreshes | Output Tokens |
|---|---|---|---|---|---|
| Claude Opus 4.5 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| 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.5 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Sonnet 4 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Sonnet 3.7 (deprecated) | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Haiku 4.5 | $1 / MTok | $1.25 / MTok | $2 / MTok | $0.10 / MTok | $5 / 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 almacenamiento en caché de indicaciones:
El almacenamiento en caché de indicaciones es una característica poderosa que optimiza el uso de tu API permitiendo reanudar desde prefijos específicos en tus indicaciones. Este enfoque reduce significativamente el tiempo de procesamiento y los costos para tareas repetitivas o indicaciones con elementos consistentes.
Aquí hay un ejemplo de cómo implementar el almacenamiento en caché de indicaciones 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{"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 una eficiencia mejorada.
Cuando envías una solicitud con el almacenamiento en caché de indicaciones habilitado:
Esto es especialmente útil para:
De forma predeterminada, 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é.
Si encuentras que 5 minutos es demasiado corto, Anthropic también ofrece una duración de caché de 1 hora con costo adicional.
Para más información, consulta duración de caché de 1 hora.
El almacenamiento en caché de indicaciones almacena en caché el prefijo completo
El almacenamiento en caché de indicaciones hace referencia a la indicación completa - tools, system, y messages (en ese orden) hasta e incluyendo el bloque designado con cache_control.
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 compatible:
| Model | Base Input Tokens | 5m Cache Writes | 1h Cache Writes | Cache Hits & Refreshes | Output Tokens |
|---|---|---|---|---|---|
| Claude Opus 4.5 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| 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.5 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Sonnet 4 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Sonnet 3.7 (deprecated) | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Haiku 4.5 | $1 / MTok | $1.25 / MTok | $2 / MTok | $0.10 / MTok | $5 / 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 almacenamiento en caché de indicaciones:
El almacenamiento en caché de indicaciones es una característica poderosa que optimiza el uso de tu API permitiendo reanudar desde prefijos específicos en tus indicaciones. Este enfoque reduce significativamente el tiempo de procesamiento y los costos para tareas repetitivas o indicaciones con elementos consistentes.
Aquí hay un ejemplo de cómo implementar el almacenamiento en caché de indicaciones 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{"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 una eficiencia mejorada.
Cuando envías una solicitud con el almacenamiento en caché de indicaciones habilitado:
Esto es especialmente útil para:
De forma predeterminada, 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é.
Si encuentras que 5 minutos es demasiado corto, Anthropic también ofrece una duración de caché de 1 hora con costo adicional.
Para más información, consulta duración de caché de 1 hora.
El almacenamiento en caché de indicaciones almacena en caché el prefijo completo
El almacenamiento en caché de indicaciones hace referencia a la indicación completa - tools, system, y messages (en ese orden) hasta e incluyendo el bloque designado con cache_control.
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 compatible:
| Model | Base Input Tokens | 5m Cache Writes | 1h Cache Writes | Cache Hits & Refreshes | Output Tokens |
|---|---|---|---|---|---|
| Claude Opus 4.5 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| 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.5 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Sonnet 4 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Sonnet 3.7 (deprecated) | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Haiku 4.5 | $1 / MTok | $1.25 / MTok | $2 / MTok | $0.10 / MTok | $5 / 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 almacenamiento en caché de indicaciones:
El almacenamiento en caché de indicaciones es actualmente compatible con:
El almacenamiento en caché de indicaciones es una característica poderosa que optimiza el uso de tu API permitiendo reanudar desde prefijos específicos en tus indicaciones. Este enfoque reduce significativamente el tiempo de procesamiento y los costos para tareas repetitivas o indicaciones con elementos consistentes.
Aquí hay un ejemplo de cómo implementar el almacenamiento en caché de indicaciones 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{"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 genera respuestas más rápidas y una eficiencia mejorada.
Cuando envías una solicitud con el almacenamiento en caché de indicaciones habilitado:
Esto es especialmente útil para:
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 almacenado en caché.
Si encuentras que 5 minutos es demasiado corto, Anthropic también ofrece una duración de caché de 1 hora a costo adicional.
Para más información, consulta duración de caché de 1 hora.
El almacenamiento en caché de indicaciones almacena el prefijo completo
El almacenamiento en caché de indicaciones hace referencia a la indicación completa - tools, system, y messages (en ese orden) hasta e incluyendo el bloque designado con cache_control.
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 compatible:
| Model | Base Input Tokens | 5m Cache Writes | 1h Cache Writes | Cache Hits & Refreshes | Output Tokens |
|---|---|---|---|---|---|
| Claude Opus 4.5 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| 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.5 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Sonnet 4 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Sonnet 3.7 (deprecated) | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Haiku 4.5 | $1 / MTok | $1.25 / MTok | $2 / MTok | $0.10 / MTok | $5 / 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 almacenamiento en caché de indicaciones:
El almacenamiento en caché de indicaciones es actualmente compatible con:
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.
Puedes usar solo un punto de ruptura de caché al final de tu contenido estático, y el sistema encontrará automáticamente la secuencia más larga de bloques almacenados en caché coincidentes. Entender cómo funciona esto te ayuda a optimizar tu estrategia de almacenamiento en caché.
Tres principios fundamentales:
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.
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.
Ventana de búsqueda hacia atrás 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 se mueve al siguiente punto de ruptura explícito (si existe).
Ejemplo: Entendiendo la ventana de búsqueda hacia atrás
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!). Dado que 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. Dado que el bloque 5 está más allá de la ventana de 20 bloques, no ocurre un 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é deberías 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.
Puedes definir hasta 4 puntos de ruptura de caché si deseas:
Limitación importante: Si tu indicación tiene más de 20 bloques de contenido antes de tu punto de ruptura de caché, y modificas contenido anterior a esos 20 bloques, no obtendrás un acierto de caché a menos que agregues puntos de ruptura explícitos adicionales más cerca de ese contenido.
La longitud mínima de indicación almacenable en caché es:
Las indicaciones más cortas 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 una indicación fue almacenada 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 duración de 5 minutos.
La longitud mínima de indicación almacenable en caché es:
Las indicaciones más cortas 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 una indicación fue almacenada 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 duración de 5 minutos.
Los puntos de ruptura de caché en sí no agregan ningún costo. Solo se te cobra por:
Agregar más puntos de ruptura cache_control no aumenta tus costos - sigues pagando la misma cantidad según el contenido que realmente se almacena en caché y se lee. Los puntos de ruptura simplemente te dan control sobre qué secciones se pueden almacenar en caché de forma independiente.
La longitud mínima de indicación almacenable en caché es:
Las indicaciones más cortas 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 una indicación fue almacenada 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 duración de 5 minutos.
Los puntos de ruptura de caché en sí no agregan ningún costo. Solo se te cobra por:
Agregar más puntos de ruptura cache_control no aumenta tus costos - sigues pagando la misma cantidad según el contenido que realmente se almacena en caché y se lee. Los puntos de ruptura simplemente te dan control sobre qué secciones se pueden almacenar en caché de forma independiente.
La mayoría de los bloques en la solicitud se pueden designar para almacenamiento en caché con cache_control. Esto incluye:
toolssystemmessages.content, para turnos de usuario y asistentemessages.content, en turnos de usuariomessages.content, en turnos de usuario y asistenteCada uno de estos elementos se puede marcar con cache_control para habilitar el almacenamiento en caché para esa parte de la solicitud.
La longitud mínima de indicación almacenable en caché es:
Las indicaciones más cortas 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 una indicación fue almacenada 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 duración de 5 minutos.
Los puntos de ruptura de caché en sí no agregan ningún costo. Solo se te cobra por:
Agregar más puntos de ruptura cache_control no aumenta tus costos - sigues pagando la misma cantidad según el contenido que realmente se almacena en caché y se lee. Los puntos de ruptura simplemente te dan control sobre qué secciones se pueden almacenar en caché de forma independiente.
Aunque la mayoría de los 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 SÍ se pueden almacenar en caché junto con otro contenido cuando aparecen en turnos anteriores del asistente. Cuando se almacenan en caché de esta manera, SÍ cuentan como tokens de entrada cuando se leen desde el 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 de origen para citas se pueden almacenar en caché. Esto te permite usar el almacenamiento en caché de indicaciones con citas de manera efectiva almacenando en caché los documentos que las citas referirán.
Los bloques de texto vacío no se pueden almacenar en caché.
La longitud mínima de indicación almacenable en caché es:
Las indicaciones más cortas 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 una indicación fue almacenada 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 duración de 5 minutos.
Los puntos de ruptura de caché en sí no agregan ningún costo. Solo se te cobra por:
Agregar más puntos de ruptura cache_control no aumenta tus costos - sigues pagando la misma cantidad según el contenido que realmente se almacena en caché y se lee. Los puntos de ruptura simplemente te dan control sobre qué secciones se pueden almacenar en caché de forma independiente.
Aunque la mayoría de los 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 SÍ se pueden almacenar en caché junto con otro contenido cuando aparecen en turnos anteriores del asistente. Cuando se almacenan en caché de esta manera, SÍ cuentan como tokens de entrada cuando se leen desde el 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 de origen para citas se pueden almacenar en caché. Esto te permite usar el almacenamiento en caché de indicaciones con citas de manera efectiva almacenando en caché los documentos que las citas referirán.
Los bloques de texto vacío no se pueden almacenar en caché.
Las modificaciones al contenido almacenado en caché pueden invalidar parte o todo el caché.
Como se describe en Estructurando 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.
| 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 búsqueda web modifica el indicador del sistema |
| Alternar citas | ✓ | ✘ | ✘ | Habilitar/deshabilitar citas modifica el indicador del sistema |
| Opción de herramienta | ✓ | ✓ | ✘ | Los cambios al parámetro tool_choice solo afectan bloques de mensajes |
| Imágenes | ✓ | ✓ | ✘ | Agregar/eliminar imágenes en cualquier lugar de la indicación afecta bloques de mensajes |
| Parámetros de pensamiento | ✓ | ✓ | ✘ | Los cambios a la configuración de pensamiento extendido (habilitar/deshabilitar, presupuesto) afectan 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 Almacenamiento en caché con bloques de pensamiento. |
La longitud mínima de indicación almacenable en caché es:
Las indicaciones más cortas 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 una indicación fue almacenada 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 duración de 5 minutos.
Los puntos de ruptura de caché en sí no agregan ningún costo. Solo se te cobra por:
Agregar más puntos de ruptura cache_control no aumenta tus costos - sigues pagando la misma cantidad según el contenido que realmente se almacena en caché y se lee. Los puntos de ruptura simplemente te dan control sobre qué secciones se pueden almacenar en caché de forma independiente.
La mayoría de los bloques en la solicitud se pueden designar para almacenamiento en caché con cache_control. Esto incluye:
toolssystemmessages.content, para turnos de usuario y asistentemessages.content, en turnos de usuariomessages.content, en turnos de usuario y asistenteCada uno de estos elementos se puede marcar con cache_control para habilitar el almacenamiento en caché para esa parte de la solicitud.
Aunque la mayoría de los 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 SÍ se pueden almacenar en caché junto con otro contenido cuando aparecen en turnos anteriores del asistente. Cuando se almacenan en caché de esta manera, SÍ cuentan como tokens de entrada cuando se leen desde el 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 de origen para citas se pueden almacenar en caché. Esto te permite usar el almacenamiento en caché de indicaciones con citas de manera efectiva almacenando en caché los documentos que las citas referirán.
Los bloques de texto vacío no se pueden almacenar en caché.
Las modificaciones al contenido almacenado en caché pueden invalidar parte o todo el caché.
Como se describe en Estructurando 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.
| 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 búsqueda web modifica el indicador del sistema |
| Alternar citas | ✓ | ✘ | ✘ | Habilitar/deshabilitar citas modifica el indicador del sistema |
| Opción de herramienta | ✓ | ✓ | ✘ | Los cambios al parámetro tool_choice solo afectan bloques de mensajes |
| Imágenes | ✓ | ✓ | ✘ | Agregar/eliminar imágenes en cualquier lugar de la indicación afecta bloques de mensajes |
| Parámetros de pensamiento | ✓ | ✓ | ✘ | Los cambios a la configuración de pensamiento extendido (habilitar/deshabilitar, presupuesto) afectan 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 Almacenamiento en caché con bloques de pensamiento. |
Monitorea el rendimiento del caché usando estos campos de respuesta de la 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 o utilizados para crear un caché (es decir, tokens después del último punto de ruptura de caché).Entendiendo el desglose de tokens
El campo input_tokens representa solo los tokens que vienen después del último punto de ruptura de caché en tu solicitud - no todos los tokens de entrada que enviaste.
Para calcular los tokens de entrada totales:
total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokensExplicación espacial:
cache_read_input_tokens = tokens antes del punto de ruptura ya almacenados en caché (lecturas)cache_creation_input_tokens = tokens antes del punto de ruptura siendo almacenados en caché ahora (escrituras)input_tokens = tokens después de tu último punto de ruptura (no elegibles para caché)Ejemplo: Si tienes una solicitud con 100,000 tokens de contenido almacenado en caché (leído desde caché), 0 tokens de contenido nuevo siendo almacenado en caché, y 50 tokens en tu mensaje de usuario (después del punto de ruptura de caché):
cache_read_input_tokens: 100,000cache_creation_input_tokens: 0input_tokens: 50Esto es importante para entender tanto costos como límites de velocidad, ya que input_tokens típicamente será mucho más pequeño que tu entrada total cuando uses almacenamiento en caché de manera efectiva.
La longitud mínima de indicación almacenable en caché es:
Las indicaciones más cortas 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 una indicación se almacenó en caché, consulte los campos de uso de respuesta.
Para solicitudes concurrentes, tenga en cuenta que una entrada de caché solo está disponible después de que comienza la primera respuesta. Si necesita aciertos de caché para solicitudes paralelas, espere a la primera respuesta antes de enviar solicitudes posteriores.
Actualmente, "ephemeral" es el único tipo de caché compatible, que por defecto tiene una vida útil de 5 minutos.
Los puntos de ruptura de caché en sí no añaden ningún costo. Solo se le cobra por:
Agregar más puntos de ruptura cache_control no aumenta sus costos: sigue pagando la misma cantidad según el contenido que realmente se almacena en caché y se lee. Los puntos de ruptura simplemente le dan control sobre qué secciones se pueden almacenar en caché de forma independiente.
La mayoría de los bloques en la solicitud se pueden designar para almacenamiento en caché con cache_control. Esto incluye:
toolssystemmessages.content, tanto para turnos de usuario como de asistentemessages.content, en turnos de usuariomessages.content, tanto para turnos de usuario como de asistenteCada uno de estos elementos se puede marcar con cache_control para habilitar el almacenamiento en caché para esa parte de la solicitud.
Aunque la mayoría de los 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 SÍ se pueden almacenar en caché junto con otro contenido cuando aparecen en turnos anteriores del asistente. Cuando se almacenan en caché de esta manera, SÍ cuentan como tokens de entrada cuando se leen desde el caché.
Los bloques de subcontenido (como citas) en sí no se pueden almacenar en caché directamente. En su lugar, almacene 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 de origen para las citas se pueden almacenar en caché. Esto le permite usar el almacenamiento en caché de indicaciones con citas de manera efectiva almacenando en caché los documentos a los que harán referencia las citas.
Los bloques de texto vacío no se pueden almacenar en caché.
Las modificaciones del contenido almacenado en caché pueden invalidar parte o todo el caché.
Como se describe en Estructuración de su 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.
| 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 la indicación del sistema |
| Alternar citas | ✓ | ✘ | ✘ | Habilitar/deshabilitar citas modifica la indicación del sistema |
| Opción de herramienta | ✓ | ✓ | ✘ | Los cambios al parámetro tool_choice solo afectan bloques de mensajes |
| Imágenes | ✓ | ✓ | ✘ | Agregar/eliminar imágenes en cualquier lugar de la indicación afecta bloques de mensajes |
| Parámetros de pensamiento | ✓ | ✓ | ✘ | Los cambios en la configuración de pensamiento extendido (habilitar/deshabilitar, presupuesto) afectan bloques de mensajes |
| Resultados que no son de herramientas pasados a solicitudes de pensamiento extendido | ✓ | ✓ | ✘ | Cuando se pasan resultados que no son de herramientas en solicitudes mientras el pensamiento extendido está habilitado, todos los bloques de pensamiento almacenados en caché previamente se eliminan del contexto, y cualquier mensaje en contexto que siga a esos bloques de pensamiento se elimina del caché. Para más detalles, consulte Almacenamiento en caché con bloques de pensamiento. |
Monitoree el rendimiento del caché utilizando estos campos de respuesta de API, dentro de usage en la respuesta (o evento message_start si transmisión):
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 se leyeron ni se utilizaron para crear un caché (es decir, tokens después del último punto de ruptura de caché).Comprensión del desglose de tokens
El campo input_tokens representa solo los tokens que vienen después del último punto de ruptura de caché en su solicitud, no todos los tokens de entrada que envió.
Para calcular el total de tokens de entrada:
total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokensExplicación espacial:
cache_read_input_tokens = tokens antes del punto de ruptura ya almacenados en caché (lecturas)cache_creation_input_tokens = tokens antes del punto de ruptura siendo almacenados en caché ahora (escrituras)input_tokens = tokens después de su último punto de ruptura (no elegibles para caché)Ejemplo: Si tiene una solicitud con 100,000 tokens de contenido almacenado en caché (lectura desde caché), 0 tokens de contenido nuevo siendo almacenado en caché, y 50 tokens en su mensaje de usuario (después del punto de ruptura de caché):
cache_read_input_tokens: 100,000cache_creation_input_tokens: 0input_tokens: 50Esto es importante para comprender tanto los costos como los límites de velocidad, ya que input_tokens será típicamente mucho más pequeño que su entrada total cuando se usa el almacenamiento en caché de manera efectiva.
Para optimizar el rendimiento del almacenamiento en caché de indicaciones:
Adapte su estrategia de almacenamiento en caché de indicaciones a su escenario:
Adapte su estrategia de almacenamiento en caché de indicaciones a su escenario:
Si experimenta un comportamiento inesperado:
tool_choice y el uso de imágenes permanezcan consistentes entre llamadascache_control adicionales anteriormente en la indicación para asegurar que todo el contenido se pueda almacenar en cachétool_use tengan un orden estable ya que algunos lenguajes (por ejemplo, Swift, Go) aleatorizan el orden de claves durante la conversión JSON, rompiendo cachésLos cambios a tool_choice o la presencia/ausencia de imágenes en cualquier lugar de la indicación invalidarán el caché, requiriendo que se cree una nueva entrada de caché. Para más detalles sobre la invalidación de caché, consulte Qué invalida el caché.
Cuando se usa 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 se pueden marcar explícitamente con cache_control, se almacenan en caché como parte del contenido de la solicitud cuando realiza llamadas de API posteriores con resultados de herramientas. Esto ocurre comúnmente durante el uso de herramientas cuando devuelve bloques de pensamiento 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 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é:
cache_control explícitosPara más detalles sobre la invalidación de caché, consulte Qué invalida el 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 presentCuando 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, consulte la documentación de pensamiento extendido.
Aislamiento de organización: Los 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, 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 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.
Adapte su estrategia de almacenamiento en caché de indicaciones a su escenario:
Si experimenta un comportamiento inesperado:
tool_choice y el uso de imágenes permanezcan consistentes entre llamadascache_control adicionales anteriormente en la indicación para asegurar que todo el contenido se pueda almacenar en cachétool_use tengan un orden estable ya que algunos lenguajes (por ejemplo, Swift, Go) aleatorizan el orden de claves durante la conversión JSON, rompiendo cachésLos cambios a tool_choice o la presencia/ausencia de imágenes en cualquier lugar de la indicación invalidarán el caché, requiriendo que se cree una nueva entrada de caché. Para más detalles sobre la invalidación de caché, consulte Qué invalida el caché.
Cuando se usa 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 se pueden marcar explícitamente con cache_control, se almacenan en caché como parte del contenido de la solicitud cuando realiza llamadas de API posteriores con resultados de herramientas. Esto ocurre comúnmente durante el uso de herramientas cuando devuelve bloques de pensamiento 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 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é:
cache_control explícitosPara más detalles sobre la invalidación de caché, consulte Qué invalida el 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 presentCuando 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, consulte la documentación de pensamiento extendido.
Aislamiento de organización: Los 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, 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 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.
Si encuentra que 5 minutos es demasiado corto, Anthropic también ofrece una duración de caché de 1 hora a costo adicional.
Para usar el caché extendido, incluya ttl en la definición cache_control así:
"cache_control": {
"type": "ephemeral",
"ttl": "5m" | "1h"
}La respuesta incluirá información detallada de 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,
}
}
}Tenga en cuenta que el campo cache_creation_input_tokens actual es igual a la suma de los valores en el objeto cache_creation.
Adapte su estrategia de almacenamiento en caché de indicaciones a su escenario:
Si experimenta un comportamiento inesperado:
tool_choice y el uso de imágenes permanezcan consistentes entre llamadascache_control adicionales anteriormente en la indicación para asegurar que todo el contenido se pueda almacenar en cachétool_use tengan un orden estable ya que algunos lenguajes (por ejemplo, Swift, Go) aleatorizan el orden de claves durante la conversión JSON, rompiendo cachésLos cambios a tool_choice o la presencia/ausencia de imágenes en cualquier lugar de la indicación invalidarán el caché, requiriendo que se cree una nueva entrada de caché. Para más detalles sobre la invalidación de caché, consulte Qué invalida el caché.
Cuando se usa 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 se pueden marcar explícitamente con cache_control, se almacenan en caché como parte del contenido de la solicitud cuando realiza llamadas de API posteriores con resultados de herramientas. Esto ocurre comúnmente durante el uso de herramientas cuando devuelve bloques de pensamiento 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 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é:
cache_control explícitosPara más detalles sobre la invalidación de caché, consulte Qué invalida el 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 presentCuando 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, consulte la documentación de pensamiento extendido.
Aislamiento de organización: Los 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, 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 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.
Si encuentra que 5 minutos es demasiado corto, Anthropic también ofrece una duración de caché de 1 hora a costo adicional.
Para usar el caché extendido, incluya ttl en la definición cache_control así:
"cache_control": {
"type": "ephemeral",
"ttl": "5m" | "1h"
}La respuesta incluirá información detallada de 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,
}
}
}Tenga en cuenta que el campo cache_creation_input_tokens actual es igual a la suma de los valores en el objeto cache_creation.
Si tiene indicaciones que se usan en una cadencia regular (es decir, indicaciones del sistema que se usan con más frecuencia que cada 5 minutos), continúe 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:
El caché de 5 minutos y 1 hora se comportan igual con respecto a la latencia. Generalmente verá un tiempo mejorado al primer token para documentos largos.
Adapta tu estrategia de almacenamiento en caché de prompts a tu escenario:
Si experimentas un comportamiento inesperado:
tool_choice y el uso de imágenes permanezcan consistentes entre llamadascache_control adicionales anteriormente en el prompt para asegurar que todo el contenido pueda almacenarse en cachétool_use tengan un orden estable, ya que algunos lenguajes (por ejemplo, Swift, Go) aleatorizan el orden de claves durante la conversión JSON, rompiendo los cachésLos cambios en 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é?.
Cuando se utiliza pensamiento extendido con almacenamiento en caché de prompts, los bloques de pensamiento tienen un comportamiento especial:
Almacenamiento en caché automático junto con otro contenido: Aunque los bloques de pensamiento no pueden marcarse explícitamente con cache_control, se almacenan en caché como parte del contenido de la 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 desde el caché, cuentan como tokens de entrada en tus métricas de uso. Esto es importante para el cálculo de costos y la presupuestación de tokens.
Patrones de invalidación del caché:
cache_control explícitosPara más detalles sobre la invalidación del 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] + [bloque tool_use 1]
Solicitud 2:
Usuario: ["¿Cuál es el clima en París?"],
Asistente: [thinking_block_1] + [bloque tool_use 1],
Usuario: [tool_result_1, cache=True]
Respuesta: [thinking_block_2] + [bloque de texto 2]
# La solicitud 2 almacena en caché su contenido de solicitud (no la respuesta)
# El caché incluye: mensaje de usuario, thinking_block_1, bloque tool_use 1, y tool_result_1
Solicitud 3:
Usuario: ["¿Cuál es el clima en París?"],
Asistente: [thinking_block_1] + [bloque tool_use 1],
Usuario: [tool_result_1, cache=True],
Asistente: [thinking_block_2] + [bloque de texto 2],
Usuario: [Respuesta de texto, cache=True]
# El bloque de usuario que no es resultado de herramientas causa que todos los bloques de pensamiento se ignoren
# Esta solicitud se procesa como si los bloques de pensamiento nunca hubieran estado presentesCuando 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 información más detallada, consulta la documentación de pensamiento extendido.
Aislamiento de Organización: Los cachés están aislados 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.
Si encuentras que 5 minutos es demasiado corto, Anthropic también ofrece una duración de caché de 1 hora a costo adicional.
Para usar el caché extendido, incluye ttl en la definición de 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 cache_creation_input_tokens actual es igual a la suma de los valores en el objeto cache_creation.
Si tienes prompts que se utilizan en una cadencia regular (es decir, prompts del sistema que se utilizan 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 utiliza mejor en los siguientes escenarios:
El caché de 5 minutos y 1 hora se comportan igual con respecto a la latencia. Generalmente verás un tiempo mejorado al primer token para documentos largos.
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 que las de TTL más corto (es decir, una entrada de caché de 1 hora debe aparecer antes que cualquier entrada de caché de 5 minutos).
Cuando se mezclan TTLs, determinamos tres ubicaciones de facturación en tu prompt:
A: El conteo de tokens en el acierto de caché más alto (o 0 si no hay aciertos).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).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 el acierto de caché más alto.
Se te cobrará por:
A.(B - A).(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, mostrado en los cuadros de colores, como resultado.
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 el almacenamiento en caché en diferentes escenarios, ayudándote a comprender las aplicaciones prácticas de esta característica: