---
title: Almacenamiento en caché de prompts
url: https://platform.claude.com/docs/es/build-with-claude/prompt-caching
description: Almacena en caché prefijos de prompts con `cache_control` para reducir costos y latencia, usando almacenamiento en caché automático o puntos de interrupción explícitos con TTL de 5 minutos o 1 hora.
---
El "prompt caching" (almacenamiento en caché de prompts) optimiza tu uso de la API al permitir reanudar desde prefijos específicos en tus prompts. Esto reduce significativamente el tiempo de procesamiento y los costos para tareas repetitivas o prompts con elementos consistentes.
Para saber cómo se aplica la "zero data retention" (retención cero de datos), o ZDR, a esta función, consulta [API y retención de datos](https://platform.claude.com/docs/es/manage-claude/api-and-data-retention).
Hay dos formas de habilitar el almacenamiento en caché de prompts:
* **[Almacenamiento en caché automático](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#automatic-caching)**: Agrega un único campo `cache_control` en el nivel superior de tu solicitud. El sistema aplica automáticamente el "cache breakpoint" (punto de interrupción de caché) al último bloque almacenable en caché y lo mueve hacia adelante a medida que crecen las conversaciones. Es ideal para conversaciones de múltiples turnos en las que el historial de mensajes creciente debe almacenarse en caché automáticamente.
* **[Puntos de interrupción de caché explícitos](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#explicit-cache-breakpoints)**: Coloca `cache_control` directamente en bloques de contenido individuales para tener un control detallado sobre exactamente qué se almacena en caché.
La forma más sencilla de empezar es con el almacenamiento en caché automático:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"cache_control": {"type": "ephemeral"},
"system": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
"messages": [
{
"role": "user",
"content": "Analyze the major themes in Pride and Prejudice."
}
]
}'
```
```bash CLI
ant messages create --transform usage <<'YAML'
model: claude-opus-5-5
max_tokens: 1024
cache_control:
type: ephemeral
system: >-
You are an AI assistant tasked with analyzing literary works. Your goal is
to provide insightful commentary on themes, characters, and writing style.
messages:
- role: user
content: Analyze the major themes in Pride and Prejudice.
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
cache_control={"type": "ephemeral"},
system="You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
messages=[
{
"role": "user",
"content": "Analyze the major themes in 'Pride and Prejudice'.",
}
],
)
print(response.usage.model_dump_json())
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
cache_control: { type: "ephemeral" },
system:
"You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
messages: [
{
role: "user",
content: "Analyze the major themes in 'Pride and Prejudice'."
}
]
});
console.log(response.usage);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
CacheControl = new CacheControlEphemeral(),
System = "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
Messages =
[
new()
{
Role = Role.User,
Content = "Analyze the major themes in 'Pride and Prejudice'."
}
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message.Usage);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
CacheControl: anthropic.NewCacheControlEphemeralParam(),
System: []anthropic.TextBlockParam{
{Text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style."},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the major themes in 'Pride and Prejudice'.")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Usage.RawJSON())
```
```java Java
import com.anthropic.models.messages.CacheControlEphemeral;
// ...
public class PromptCachingExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.cacheControl(CacheControlEphemeral.builder().build())
.system("You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.")
.addUserMessage("Analyze the major themes in 'Pride and Prejudice'.")
.build();
Message message = client.messages().create(params);
System.out.println(message.usage());
}
}
```
```php PHP
use Anthropic\Messages\CacheControlEphemeral;
// ...
$client = new Client();
$response = $client->messages->create(
maxTokens: 1024,
messages: [
['role' => 'user', 'content' => "Analyze the major themes in 'Pride and Prejudice'."]
],
model: 'claude-opus-5-5',
cacheControl: CacheControlEphemeral::with(),
system: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
);
echo json_encode($response->usage);
```
```ruby Ruby
client = Anthropic::Client.new
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
cache_control: {type: "ephemeral"},
system: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
messages: [
{
role: "user",
content: "Analyze the major themes in 'Pride and Prejudice'."
}
]
)
puts response.usage
```
Con el almacenamiento en caché automático, el sistema almacena en caché todo el contenido hasta el último bloque almacenable en caché, inclusive. En solicitudes posteriores con el mismo prefijo, el contenido en caché se reutiliza automáticamente.
***
## 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 del prompt, hasta un punto de interrupción de caché especificado, ya está almacenado en caché a partir de una consulta reciente.
2. Si lo encuentra, usa la versión en caché, lo que reduce el tiempo de procesamiento y los costos.
3. De lo contrario, procesa el prompt completo y almacena en caché el prefijo una vez que comienza la respuesta.
Esto es especialmente útil para:
* Prompts con muchos ejemplos
* Grandes cantidades de contexto o información de fondo
* Tareas repetitivas con instrucciones consistentes
* Conversaciones largas de múltiples turnos
De forma predeterminada, la caché tiene una vida útil de 5 minutos. La caché se actualiza sin costo adicional cada vez que se usa el contenido almacenado en caché.
La vida útil se mide desde el inicio de la solicitud que escribe o lee la entrada de caché, no desde el final de su respuesta. El tiempo dedicado a generar una respuesta cuenta contra la vida útil: si una respuesta tarda 4 minutos en hacer streaming, una solicitud de seguimiento que reutilice el mismo prefijo en caché debe comenzar aproximadamente dentro de 1 minuto después de que se complete esa respuesta.
Si consideras que 5 minutos es muy poco tiempo, Anthropic también ofrece una duración de caché de 1 hora [con un costo adicional](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#pricing).
Para obtener más información, consulta [Duración de caché de 1 hora](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#1-hour-cache-duration).
**El almacenamiento en caché de prompts almacena el prefijo completo**
El almacenamiento en caché de prompts hace referencia al prompt completo: `tools`, `system` y `messages` (en ese orden), hasta el bloque designado con `cache_control`, inclusive.
***
## Precios
El almacenamiento en caché de prompts introduce una nueva estructura de precios. La siguiente tabla muestra el precio por millón de tokens para cada modelo compatible:
| Model | Base input tokens | 5m cache writes | 1h cache writes | Cache hits and refreshes | Output tokens |
| :----------------------------------------------------------------------------------------------------------------------------------- | :---------------- | :-------------- | :-------------- | :----------------------- | :------------ |
| Claude Fable 5.1 | $10 / MTok | $12.50 / MTok | $20 / MTok | $0.25 / MTok1 | $50 / MTok |
| Claude Mythos 5.1 ([limited availability](https://support.claude.com/en/articles/14604842)) | $10 / MTok | $12.50 / MTok | $20 / MTok | $0.25 / MTok1 | $50 / MTok |
| Claude Fable 5 | $10 / MTok | $12.50 / MTok | $20 / MTok | $1 / MTok | $50 / MTok |
| Claude Mythos 5 ([limited availability](https://support.claude.com/en/articles/14604842)) | $10 / MTok | $12.50 / MTok | $20 / MTok | $1 / MTok | $50 / MTok |
| Claude Opus 5.5 | $4 / MTok | $5 / MTok | $8 / MTok | $0.20 / MTok2 | $20 / MTok |
| Claude Opus 5 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.8 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.7 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.6 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.5 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.1 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/es/about-claude/model-deprecations)) | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Opus 4 ([retired, except on Google Cloud](https://platform.claude.com/docs/es/about-claude/model-deprecations)) | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Sonnet 5.5 | $2 / MTok | $2.50 / MTok | $4 / MTok | $0.10 / MTok2 | $10 / MTok |
| Claude Sonnet 5 | $2 / MTok | $2.50 / MTok | $4 / MTok | $0.20 / MTok | $10 / MTok |
| Claude Sonnet 4.6 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Sonnet 4.5 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Sonnet 4 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/es/about-claude/model-deprecations)) | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Haiku 5.5 (for prompts up to 100,000 tokens) | $0.10 / MTok | $0.125 / MTok | $0.20 / MTok | $0.01 / MTok | $0.50 / MTok |
| Claude Haiku 5.5 (for prompts over 100,000 tokens) | $0.50 / MTok | $0.625 / MTok | $1 / MTok | $0.05 / MTok | $2.50 / MTok |
| Claude Haiku 4.5 | $1 / MTok | $1.25 / MTok | $2 / MTok | $0.10 / MTok | $5 / MTok |
| Claude Haiku 3.5 ([retired, except on Google Cloud](https://platform.claude.com/docs/es/about-claude/model-deprecations)) | $0.80 / MTok | $1 / MTok | $1.60 / MTok | $0.08 / MTok | $4 / MTok |
*1 Cache hits and refreshes on Claude Fable 5.1 and Claude Mythos 5.1 are priced at 0.025x the base input price.*
*2 Cache hits and refreshes on Claude Opus 5.5 and Claude Sonnet 5.5 are priced at 0.05x the base input price.*
*All other models use the standard 0.1x multiplier.*
La tabla anterior refleja los siguientes multiplicadores de precios para el almacenamiento en caché de prompts:
* Los tokens de escritura en caché de 5 minutos cuestan 1.25 veces el precio base de los tokens de entrada
* Los tokens de escritura en caché de 1 hora cuestan 2 veces el precio base de los tokens de entrada
* Los tokens de lectura de caché cuestan 0.1 veces el precio base de los tokens de entrada (consulta la nota al pie de la tabla para ver las excepciones por modelo)
Estos multiplicadores se combinan con otros modificadores de precios, como el descuento de la Batch API, los [precios de contexto largo](https://platform.claude.com/docs/es/about-claude/pricing#long-context-pricing) y la residencia de datos. En un modelo cuyo precio depende de la longitud del prompt, las lecturas y escrituras de caché cuentan para la longitud del prompt de una solicitud. Consulta [precios](https://platform.claude.com/docs/es/about-claude/pricing) para ver todos los detalles.
***
## Modelos compatibles
El almacenamiento en caché de prompts (tanto automático como explícito) es compatible con todos los [modelos activos de Claude](https://platform.claude.com/docs/es/models/overview).
***
## Almacenamiento en caché automático
El almacenamiento en caché automático es la forma más sencilla de habilitar el almacenamiento en caché de prompts. En lugar de colocar `cache_control` en bloques de contenido individuales, agrega un único campo `cache_control` en el nivel superior del cuerpo de tu solicitud. El sistema aplica automáticamente el punto de interrupción de caché al último bloque almacenable en caché.
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"cache_control": {"type": "ephemeral"},
"system": "You are a helpful assistant that remembers our conversation.",
"messages": [
{"role": "user", "content": "My name is Alex. I work on machine learning."},
{"role": "assistant", "content": "Nice to meet you, Alex! How can I help with your ML work today?"},
{"role": "user", "content": "What did I say I work on?"}
]
}'
```
```bash CLI
ant messages create --transform usage <<'YAML'
model: claude-opus-5-5
max_tokens: 1024
cache_control:
type: ephemeral
system: You are a helpful assistant that remembers our conversation.
messages:
- role: user
content: My name is Alex. I work on machine learning.
- role: assistant
content: Nice to meet you, Alex! How can I help with your ML work today?
- role: user
content: What did I say I work on?
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
cache_control={"type": "ephemeral"},
system="You are a helpful assistant that remembers our conversation.",
messages=[
{"role": "user", "content": "My name is Alex. I work on machine learning."},
{
"role": "assistant",
"content": "Nice to meet you, Alex! How can I help with your ML work today?",
},
{"role": "user", "content": "What did I say I work on?"},
],
)
print(response.usage.model_dump_json())
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
cache_control: { type: "ephemeral" },
system: "You are a helpful assistant that remembers our conversation.",
messages: [
{ role: "user", content: "My name is Alex. I work on machine learning." },
{
role: "assistant",
content: "Nice to meet you, Alex! How can I help with your ML work today?"
},
{ role: "user", content: "What did I say I work on?" }
]
});
console.log(response.usage);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
CacheControl = new CacheControlEphemeral(),
System = "You are a helpful assistant that remembers our conversation.",
Messages =
[
new()
{
Role = Role.User,
Content = "My name is Alex. I work on machine learning."
},
new()
{
Role = Role.Assistant,
Content = "Nice to meet you, Alex! How can I help with your ML work today?"
},
new()
{
Role = Role.User,
Content = "What did I say I work on?"
}
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message.Usage);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
CacheControl: anthropic.NewCacheControlEphemeralParam(),
System: []anthropic.TextBlockParam{
{Text: "You are a helpful assistant that remembers our conversation."},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("My name is Alex. I work on machine learning.")),
anthropic.NewAssistantMessage(anthropic.NewTextBlock("Nice to meet you, Alex! How can I help with your ML work today?")),
anthropic.NewUserMessage(anthropic.NewTextBlock("What did I say I work on?")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Usage.RawJSON())
```
```java Java
import com.anthropic.models.messages.CacheControlEphemeral;
// ...
public class AutomaticCachingExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.cacheControl(CacheControlEphemeral.builder().build())
.system("You are a helpful assistant that remembers our conversation.")
.addUserMessage("My name is Alex. I work on machine learning.")
.addAssistantMessage("Nice to meet you, Alex! How can I help with your ML work today?")
.addUserMessage("What did I say I work on?")
.build();
Message message = client.messages().create(params);
System.out.println(message.usage());
}
}
```
```php PHP
use Anthropic\Messages\CacheControlEphemeral;
// ...
$client = new Client();
$response = $client->messages->create(
maxTokens: 1024,
messages: [
['role' => 'user', 'content' => 'My name is Alex. I work on machine learning.'],
['role' => 'assistant', 'content' => 'Nice to meet you, Alex! How can I help with your ML work today?'],
['role' => 'user', 'content' => 'What did I say I work on?'],
],
model: 'claude-opus-5-5',
cacheControl: CacheControlEphemeral::with(),
system: 'You are a helpful assistant that remembers our conversation.',
);
echo json_encode($response->usage);
```
```ruby Ruby
client = Anthropic::Client.new
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
cache_control: {type: "ephemeral"},
system: "You are a helpful assistant that remembers our conversation.",
messages: [
{role: "user", content: "My name is Alex. I work on machine learning."},
{role: "assistant", content: "Nice to meet you, Alex! How can I help with your ML work today?"},
{role: "user", content: "What did I say I work on?"}
]
)
puts response.usage
```
### Cómo funciona el almacenamiento en caché automático en conversaciones de múltiples turnos
Con el almacenamiento en caché automático, el punto de caché avanza automáticamente a medida que crecen las conversaciones. Cada nueva solicitud almacena en caché todo hasta el último bloque almacenable en caché, y el contenido anterior se lee desde la caché.
| Solicitud | Contenido | Comportamiento de la caché |
| ----------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| Solicitud 1 | System
+ User(1) + Asst(1)
+ **User(2)** ◀ caché | Todo se escribe en la caché |
| Solicitud 2 | System
+ User(1) + Asst(1)
+ User(2) + Asst(2)
+ **User(3)** ◀ caché | Desde System hasta User(2) se lee desde la caché;
Asst(2) + User(3) se escriben en la caché |
| Solicitud 3 | System
+ User(1) + Asst(1)
+ User(2) + Asst(2)
+ User(3) + Asst(3)
+ **User(4)** ◀ caché | Desde System hasta User(3) se lee desde la caché;
Asst(3) + User(4) se escriben en la caché |
El punto de interrupción de caché se mueve automáticamente al último bloque almacenable en caché en cada solicitud, por lo que no necesitas actualizar ningún marcador `cache_control` a medida que crece la conversación.
### Compatibilidad con TTL
De forma predeterminada, el almacenamiento en caché automático usa un "TTL" (tiempo de vida) de 5 minutos. Puedes especificar un TTL de 1 hora a 2 veces el precio base de los tokens de entrada:
```json
{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }
```
### Combinación con el almacenamiento en caché a nivel de bloque
El almacenamiento en caché automático es compatible con los [puntos de interrupción de caché explícitos](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#explicit-cache-breakpoints). Cuando se usan juntos, el punto de interrupción de caché automático ocupa uno de los 4 espacios de puntos de interrupción disponibles.
Esto te permite combinar ambos enfoques. Por ejemplo, usa un punto de interrupción explícito para almacenar en caché tu indicación del sistema, mientras el almacenamiento en caché automático se encarga de la conversación:
```json
{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"cache_control": { "type": "ephemeral" },
"system": [
{
"type": "text",
"text": "You are a helpful assistant.",
"cache_control": { "type": "ephemeral" }
}
],
"messages": [{ "role": "user", "content": "What are the key terms?" }]
}
```
### Lo que se mantiene igual
El almacenamiento en caché automático usa la misma infraestructura de caché subyacente. Los precios, los umbrales mínimos de tokens, los requisitos de orden del contexto y la ventana de retrospección de 20 bloques se aplican de la misma manera que con los puntos de interrupción explícitos.
### Casos límite
* Si el último bloque ya tiene un `cache_control` explícito con el mismo TTL, el almacenamiento en caché automático no tiene ningún efecto.
* Si el último bloque tiene un `cache_control` explícito con un TTL diferente, la API devuelve un error 400.
* Si ya existen 4 puntos de interrupción explícitos a nivel de bloque, la API devuelve un error 400 (no quedan espacios para el almacenamiento en caché automático).
* Si el último bloque no es apto como destino de un punto de interrupción de caché automático, el sistema retrocede silenciosamente para encontrar el bloque apto más cercano. Si no encuentra ninguno, se omite el almacenamiento en caché.
El almacenamiento en caché automático está disponible en todas las plataformas excepto en la integración heredada de [Amazon Bedrock (Opus 4.6 y anteriores)](https://platform.claude.com/docs/es/build-with-claude/claude-on-amazon-bedrock-legacy). En esa integración, la API devuelve un error 400 para un campo `cache_control` de nivel superior, así que usa [puntos de interrupción de caché explícitos](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#explicit-cache-breakpoints) en su lugar.
***
## Puntos de interrupción de caché explícitos
Para tener más control sobre el almacenamiento en caché, puedes colocar `cache_control` directamente en bloques de contenido individuales. Esto es útil cuando necesitas almacenar en caché diferentes secciones que cambian con distintas frecuencias, o cuando necesitas un control detallado sobre exactamente qué se almacena en caché.
### Estructurar tu prompt
Coloca el contenido estático (definiciones de herramientas, instrucciones del sistema, contexto, ejemplos) al principio de tu prompt. Marca el final del contenido reutilizable para almacenarlo en caché usando el parámetro `cache_control`.
Los prefijos de caché se crean en el siguiente orden: `tools`, `system` y luego `messages`. Este orden forma una jerarquía en la que cada nivel se construye sobre los anteriores.
#### Cómo funciona la verificación automática de prefijos
Puedes usar un solo punto de interrupción de caché al final de tu contenido estático, y el sistema encontrará automáticamente el prefijo más largo que una solicitud anterior ya haya escrito en la caché. Entender cómo funciona esto te ayuda a optimizar tu estrategia de almacenamiento en caché.
**Tres principios fundamentales:**
1. **Las escrituras en caché ocurren solo en tu punto de interrupción.** Marcar un bloque con `cache_control` escribe exactamente una entrada de caché: un hash del prefijo que termina en ese bloque. El sistema no escribe entradas para ninguna posición anterior. Como el hash es acumulativo y abarca todo hasta el punto de interrupción, inclusive, cambiar cualquier bloque en el punto de interrupción o antes de él produce un hash diferente en la siguiente solicitud.
2. **Las lecturas de caché buscan hacia atrás entradas que escribieron solicitudes anteriores.** En cada solicitud, el sistema calcula el hash del prefijo en tu punto de interrupción y busca una entrada de caché coincidente. Si no existe ninguna, retrocede un bloque a la vez y verifica si el hash del prefijo en cada posición anterior coincide con algo que ya esté en la caché. Busca escrituras anteriores, no contenido estable.
3. **La "lookback window" (ventana de retrospección) es de 20 bloques.** El sistema verifica como máximo 20 posiciones por punto de interrupción, contando el propio punto de interrupción como la primera. Si el sistema no encuentra ninguna entrada coincidente en esa ventana, la verificación se detiene (o se reanuda desde el siguiente punto de interrupción explícito, si lo hay). En la Claude API, una serie de bloques `tool_use` consecutivos cuenta como una sola posición, al igual que una serie de bloques `tool_result` consecutivos, por lo que un turno con muchas llamadas a herramientas en paralelo no saca por sí solo la entrada de la solicitud anterior fuera de la ventana.
**Ejemplo: Retrospección en una conversación creciente**
Agregas nuevos bloques en cada turno y estableces `cache_control` en el bloque final de cada solicitud:
* **Turno 1:** 10 bloques, punto de interrupción en el bloque 10. No existen entradas de caché previas. El sistema escribe una entrada en el bloque 10.
* **Turno 2:** 15 bloques, punto de interrupción en el bloque 15. El bloque 15 no tiene entrada, así que el sistema retrocede hasta el bloque 10 y encuentra la entrada del turno 1. Acierto de caché en el bloque 10; el sistema procesa desde cero solo los bloques 11 a 15 y escribe una nueva entrada en el bloque 15.
* **Turno 3:** 35 bloques, punto de interrupción en el bloque 35. El sistema verifica 20 posiciones (bloques 35 a 16) y no encuentra nada. La entrada del turno 2 en el bloque 15 está una posición fuera de la ventana, por lo que no hay acierto de caché. Agregar un segundo punto de interrupción en el bloque 15 inicia allí una segunda ventana de retrospección, que encuentra la entrada del turno 2.
**Error común: Punto de interrupción en contenido que cambia en cada solicitud**
Tu prompt tiene un contexto de sistema estático grande (bloques 1 a 5) seguido de un bloque por solicitud que contiene una marca de tiempo y el mensaje del usuario (bloque 6). Estableces `cache_control` en el bloque 6:
* **Solicitud 1:** Escritura en caché en el bloque 6. El hash incluye la marca de tiempo.
* **Solicitud 2:** La marca de tiempo es diferente, por lo que el hash del prefijo en el bloque 6 es diferente. La retrospección recorre los bloques 5, 4, 3, 2 y 1, pero el sistema nunca escribió una entrada en ninguna de esas posiciones. No hay acierto de caché. Pagas por una nueva escritura en caché en cada solicitud y nunca obtienes una lectura.
La retrospección no encuentra contenido estable detrás de tu punto de interrupción para almacenarlo en caché. Encuentra entradas que solicitudes anteriores ya escribieron, y las escrituras ocurren solo en los puntos de interrupción. Mueve `cache_control` al bloque 5, el último bloque que se mantiene igual entre solicitudes, y cada solicitud posterior leerá el prefijo en caché. El [almacenamiento en caché automático](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#automatic-caching) cae en la misma trampa: coloca el punto de interrupción en el último bloque almacenable en caché, que en esta estructura es el que cambia en cada solicitud, así que usa un punto de interrupción explícito en el bloque 5 en su lugar.
**Conclusión clave:** Coloca `cache_control` en el último bloque cuyo prefijo sea idéntico en las solicitudes que quieres que compartan una caché. En una conversación creciente, el bloque final funciona siempre que cada turno agregue menos de 20 bloques: el contenido anterior nunca cambia, por lo que la retrospección de la siguiente solicitud encuentra la escritura anterior. Para un prompt con un sufijo variable (marcas de tiempo, contexto por solicitud, el mensaje entrante), coloca el punto de interrupción al final del prefijo estático, no en el bloque variable.
#### Cuándo usar múltiples puntos de interrupción
Puedes definir hasta 4 puntos de interrupción de caché si quieres:
* Almacenar en caché diferentes secciones que cambian con distintas frecuencias (por ejemplo, las herramientas rara vez cambian, pero el contexto se actualiza a diario)
* Tener más control sobre exactamente qué se almacena en caché
* Garantizar un acierto de caché cuando una conversación creciente empuja tu punto de interrupción 20 o más bloques más allá de la última escritura en caché
**Limitación importante:** La retrospección solo puede encontrar entradas que solicitudes anteriores ya escribieron. Si una conversación creciente empuja tu punto de interrupción 20 o más bloques más allá de la última escritura, la ventana de retrospección no la encuentra. Agrega desde el principio un segundo punto de interrupción más cerca de esa posición para que se acumule una escritura allí antes de que la necesites.
### Entender los costos de los puntos de interrupción de caché
**Los puntos de interrupción de caché en sí no agregan ningún costo.** Solo se te cobra por:
* **Escrituras en caché:** Cuando se escribe contenido nuevo en la caché (25% más que los tokens de entrada base para un TTL de 5 minutos)
* **Lecturas de caché:** Cuando se usa contenido en caché (10% del precio base de los tokens de entrada, o 2.5% en Claude Fable 5.1 y Claude Mythos 5.1, y 5% en Claude Opus 5.5 y Claude Sonnet 5.5)
* **Tokens de entrada regulares:** Por cualquier contenido que no esté en caché
Agregar más puntos de interrupción `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 interrupción te dan control sobre qué secciones se pueden almacenar en caché de forma independiente.
***
## Estrategias y consideraciones de almacenamiento en caché
### Limitaciones de la caché
En la Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/es/build-with-claude/claude-platform-on-aws), [Google Cloud](https://platform.claude.com/docs/es/build-with-claude/claude-on-vertex-ai) y [Microsoft Foundry](https://platform.claude.com/docs/es/build-with-claude/claude-in-microsoft-foundry), la longitud mínima de prompt almacenable en caché es:
* 512 tokens para Claude Fable 5.1, [Claude Mythos 5.1](https://platform.claude.com/docs/es/models/mythos-5-1/overview), Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Fable 5, [Claude Mythos 5](https://platform.claude.com/docs/es/models/mythos-5/overview) y Claude Haiku 5.5
* 2,048 tokens para [Claude Mythos Preview](https://anthropic.com/glasswing) y Claude Opus 4.7
* 4,096 tokens para Claude Opus 4.6 y Claude Opus 4.5
* 1,024 tokens para Claude Opus 4.8, Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5 ([obsoleto](https://platform.claude.com/docs/es/about-claude/model-deprecations)), Claude Opus 4.1 ([retirado, excepto en Bedrock y Google Cloud](https://platform.claude.com/docs/es/about-claude/model-deprecations)), Claude Opus 4 ([retirado, excepto en Google Cloud](https://platform.claude.com/docs/es/about-claude/model-deprecations)) y Claude Sonnet 4 ([retirado, excepto en Bedrock y Google Cloud](https://platform.claude.com/docs/es/about-claude/model-deprecations))
* 4,096 tokens para Claude Haiku 4.5
* 2,048 tokens para Claude Haiku 3.5 ([retirado, excepto en Google Cloud](https://platform.claude.com/docs/es/about-claude/model-deprecations))
Estos mínimos se aplican en todas las plataformas donde cada modelo está disponible.
Los prompts más cortos no se pueden almacenar en caché, incluso si están marcados con `cache_control`. Cualquier solicitud para almacenar en caché menos de esta cantidad de tokens se procesará sin almacenamiento en caché, y no se devuelve ningún error. Para verificar si un prompt se almacenó en caché, revisa los [campos de uso de la respuesta](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#tracking-cache-performance): si tanto `cache_creation_input_tokens` como `cache_read_input_tokens` son 0, el prompt no se almacenó en caché (probablemente porque no cumplió con el requisito de longitud mínima).
Si tu prompt se queda justo por debajo del mínimo para tu modelo y plataforma, a menudo vale la pena ampliar el contenido en caché para alcanzar el umbral. Las lecturas de caché cuestan significativamente menos que los tokens de entrada sin caché, por lo que alcanzar el mínimo puede reducir los costos de los prompts que se reutilizan con frecuencia.
[Bedrock](https://platform.claude.com/docs/es/build-with-claude/claude-in-amazon-bedrock) es una plataforma operada por AWS. En Bedrock, consulta la [documentación de almacenamiento en caché de prompts de Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html) para conocer los mínimos por modelo, el comportamiento ante fallos y los nombres de los campos de uso que se aplican.
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 en paralelo, espera a la primera respuesta antes de enviar las solicitudes posteriores.
Actualmente, "ephemeral" es el único tipo de caché compatible, que de forma predeterminada tiene una vida útil de 5 minutos.
### Qué se puede almacenar en caché
La mayoría de los bloques de la solicitud se pueden almacenar en caché. Esto incluye:
* Herramientas: Definiciones de herramientas en el arreglo `tools`
* Mensajes del sistema: Bloques de contenido en el arreglo `system`
* Mensajes de texto: Bloques de contenido en el arreglo `messages.content`, tanto para turnos del usuario como del asistente
* Imágenes y documentos: Bloques de contenido en el arreglo `messages.content`, en turnos del usuario
* Uso de herramientas y resultados de herramientas: Bloques de contenido en el arreglo `messages.content`, tanto en turnos del usuario como del asistente
Cada uno de estos elementos se puede almacenar en caché, ya sea automáticamente o marcándolos con `cache_control`.
### Qué no se puede almacenar en caché
Aunque la mayoría de los bloques de la 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 la caché.
* Los bloques de subcontenido (como las [citas](https://platform.claude.com/docs/es/build-with-claude/citations)) no se pueden almacenar en caché directamente. En su lugar, almacena en caché el bloque de nivel superior.
En el caso de las citas, los bloques de contenido de documento de nivel superior que sirven como material fuente para las citas sí se pueden almacenar en caché. Esto te permite usar el almacenamiento en caché de prompts con citas de forma eficaz, almacenando en caché los documentos a los que harán referencia las citas.
* Los bloques de texto vacíos no se pueden almacenar en caché.
### Qué invalida la caché
Las modificaciones al contenido en caché pueden invalidar parte o la totalidad de la caché.
Como se describe en [Estructurar tu prompt](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#structuring-your-prompt), la 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 de la caché se invalidan con diferentes tipos de cambios. ✘ indica que la caché se invalida, mientras que ✓ indica que la caché sigue siendo válida.
| Qué cambia | Caché de herramientas | Caché del sistema | Caché de mensajes | Impacto |
| ------------------------------------------------------------------------------- | --------------------- | --------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Definiciones de herramientas** | ✘ | ✘ | ✘ | Modificar las definiciones de herramientas (nombres, descripciones, parámetros) invalida toda la caché |
| **Activación de búsqueda web** | ✓ | ✘ | ✘ | Habilitar/deshabilitar la búsqueda web modifica la indicación del sistema |
| **Activación de citas** | ✓ | ✘ | ✘ | Habilitar/deshabilitar las citas modifica la indicación del sistema |
| **Configuración de velocidad** | ✓ | ✘ | ✘ | Cambiar entre [`speed: "fast"` y la velocidad estándar](https://platform.claude.com/docs/es/build-with-claude/fast-mode) invalida las cachés del sistema y de mensajes |
| **Elección de herramienta** | ✓ | ✓ | ✘ | Los cambios en el parámetro `tool_choice` solo afectan a los bloques de mensajes |
| **Imágenes** | ✓ | ✓ | ✘ | Agregar/eliminar imágenes en cualquier parte del prompt afecta a los bloques de mensajes |
| **Parámetros de pensamiento** | Específico del modelo | Específico del modelo | ✘ | La configuración de pensamiento (el modo y `budget_tokens` en el modo extendido) se incorpora al prompt, por lo que cambiarla siempre invalida los bloques de mensajes; las cachés de herramientas y del sistema también se invalidan en los modelos que incorporan la configuración antes que ellas. Consulta [Pensamiento y almacenamiento en caché de prompts](https://platform.claude.com/docs/es/build-with-claude/thinking#thinking-and-prompt-caching). |
| **Configuración de esfuerzo** | Específico del modelo | Específico del modelo | ✘ | Cambiar el valor de [`output_config.effort`](https://platform.claude.com/docs/es/build-with-claude/effort) siempre invalida los bloques de mensajes, con el mismo efecto específico del modelo sobre las cachés de herramientas y del sistema que los parámetros de pensamiento. Establecer el esfuerzo explícitamente en el valor predeterminado del modelo equivale a omitirlo y no invalida la caché. En los modelos que admiten [esfuerzo por mensaje](https://platform.claude.com/docs/es/build-with-claude/effort#change-effort-mid-conversation-beta), un cambio de esfuerzo incluido en un mensaje `role: "system"` dentro de `messages` deja intacto el prefijo en caché. |
| **Resultados que no son de herramientas pasados a solicitudes con pensamiento** | ✓ | ✓ | Específico del modelo | En Opus 4.5+, Sonnet 4.6+ y Haiku 5.5, los bloques de pensamiento se conservan de forma predeterminada, por lo que la caché sigue siendo válida (✓). En modelos Opus/Sonnet anteriores y en modelos Haiku hasta Claude Haiku 4.5, todos los bloques de pensamiento previamente almacenados en caché se eliminan del contexto, y cualquier mensaje que siga a esos bloques de pensamiento se elimina de la caché (✘). Para obtener más detalles, consulta [Almacenamiento en caché con bloques de pensamiento](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#caching-with-thinking-blocks). |
| **Bloques de pensamiento descartados** | ✓ | ✓ | ✘ | Cuando la API descarta un bloque de pensamiento de Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5 o Claude Haiku 5.5 que no se [conserva](https://platform.claude.com/docs/es/build-with-claude/thinking#preserved-thinking) en esa solicitud (por ejemplo, uno que reenvías a un modelo que no puede leerlo), el prefijo en caché cambia a partir de la posición de ese bloque en esa solicitud. Los bloques que el modelo receptor puede leer, devueltos sin cambios, mantienen la caché intacta. |
En los modelos que admiten [cambios de herramientas a mitad de la conversación](https://platform.claude.com/docs/es/build-with-claude/mid-conversation-system-messages#mid-conversation-tool-changes), el encabezado beta `inline-tools-2026-09-15` te permite agregar una herramienta, o cambiar la definición de una herramienta, a mitad de una conversación sin editar `tools`. Envía la definición en un bloque `tool_addition` dentro de un mensaje del sistema a mitad de la conversación y deja `tools` exactamente como lo enviaste la primera vez. El prefijo en caché sigue coincidiendo, por lo que solo el mensaje agregado se procesa como entrada nueva. La única excepción es un arreglo `tools` sin ninguna herramienta no diferida, en cuyo caso la primera herramienta definida de esta manera cuesta un fallo de caché completo en esa solicitud. Consulta [Definir herramientas en un mensaje](https://platform.claude.com/docs/es/build-with-claude/mid-conversation-system-messages#define-tools-in-a-message-beta).
En Claude Fable 5.1, [Claude Mythos 5.1](https://platform.claude.com/docs/es/models/mythos-5-1/overview), Claude Fable 5, [Claude Mythos 5](https://platform.claude.com/docs/es/models/mythos-5/overview), Claude Opus 5.5, Claude Opus 4.8, Claude Opus 5, Claude Sonnet 5.5 y Claude Haiku 5.5, puedes agregar una nueva instrucción del sistema a mitad de una conversación sin invalidar las cachés del sistema ni de mensajes. Agrega un mensaje `{"role": "system"}` a `messages` en lugar de editar el campo `system` de nivel superior, para que el prefijo en caché se mantenga sin cambios. Esta función no está disponible en Claude Sonnet 5. Usa el campo `system` de nivel superior en su lugar. Consulta [Mensajes del sistema a mitad de la conversación](https://platform.claude.com/docs/es/build-with-claude/mid-conversation-system-messages).
### Seguimiento del rendimiento de la caché
Supervisa el rendimiento de la caché usando estos campos de respuesta de la API, dentro de `usage` en la respuesta (o en el evento `message_start` si usas [streaming](https://platform.claude.com/docs/es/build-with-claude/streaming)):
* `cache_creation_input_tokens`: Número de tokens escritos en la caché al crear una nueva entrada.
* `cache_read_input_tokens`: Número de tokens recuperados de la caché para esta solicitud.
* `input_tokens`: Número de tokens de entrada que no se leyeron de una caché ni se usaron para crearla (es decir, los tokens después del último punto de interrupción de caché).
**Entender el desglose de tokens**
El campo `input_tokens` representa solo los tokens que vienen **después del último punto de interrupción de caché** en tu solicitud, no todos los tokens de entrada que enviaste.
Para calcular el total de tokens de entrada:
```text wrap
total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens
```
**Explicación espacial:**
* `cache_read_input_tokens` = tokens antes del punto de interrupción que ya están en caché (lecturas)
* `cache_creation_input_tokens` = tokens antes del punto de interrupción que se están almacenando en caché ahora (escrituras)
* `input_tokens` = tokens después de tu último punto de interrupción (no aptos para caché)
**Ejemplo:** Si tienes una solicitud con 100,000 tokens de contenido en caché (leídos desde la caché), 0 tokens de contenido nuevo que se está almacenando en caché y 50 tokens en tu mensaje de usuario (después del punto de interrupción de caché):
* `cache_read_input_tokens`: 100,000
* `cache_creation_input_tokens`: 0
* `input_tokens`: 50
* **Total de tokens de entrada procesados:** 100,050 tokens
Esto es importante para entender tanto los costos como los límites de velocidad, ya que `input_tokens` normalmente será mucho menor que tu entrada total cuando usas el almacenamiento en caché de forma eficaz.
### Almacenamiento en caché con bloques de pensamiento
Cuando usas el [pensamiento](https://platform.claude.com/docs/es/build-with-claude/thinking) con el 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 se pueden marcar explícitamente con `cache_control`, se almacenan en caché como parte del contenido de la solicitud cuando realizas llamadas posteriores a la API con resultados de herramientas. Esto suele ocurrir durante el uso de herramientas, cuando devuelves los bloques de pensamiento para continuar la conversación.
**Conteo de tokens de entrada:** Cuando los bloques de pensamiento se leen desde la caché, cuentan como tokens de entrada en tus métricas de uso. Esto es importante para el cálculo de costos y la planificación del presupuesto de tokens.
**Patrones de invalidación de la caché:**
* La caché sigue siendo válida cuando solo se proporcionan resultados de herramientas como mensajes del usuario
* En Opus 4.5+, Sonnet 4.6+ y Haiku 5.5, los bloques de pensamiento se conservan de forma predeterminada incluso cuando se agrega contenido del usuario que no es un resultado de herramienta, por lo que la caché sigue siendo válida
* En los modelos Opus/Sonnet anteriores y los modelos Haiku hasta Claude Haiku 4.5, la caché se invalida cuando se agrega contenido del usuario que no es un resultado de herramienta, lo que hace que todos los bloques de pensamiento anteriores se eliminen del contexto
* Este comportamiento de almacenamiento en caché ocurre incluso sin marcadores `cache_control` explícitos
Para obtener más detalles sobre la invalidación de la caché, consulta [Qué invalida la caché](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#what-invalidates-the-cache).
**Ejemplo con uso de herramientas:**
```text wrap
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]
# Depending on the model, this non-tool-result user block either keeps prior thinking blocks or strips them (see the next paragraph)
```
En los modelos Opus/Sonnet anteriores y los modelos Haiku hasta Claude Haiku 4.5, todos los bloques de pensamiento anteriores se eliminan del contexto en este punto. En Opus 4.5+, Sonnet 4.6+ y Haiku 5.5, los bloques de pensamiento anteriores se conservan de forma predeterminada y siguen formando parte del prefijo en caché.
Para obtener información más detallada, consulta [Pensamiento y almacenamiento en caché de prompts](https://platform.claude.com/docs/es/build-with-claude/thinking#thinking-and-prompt-caching).
### Almacenamiento y uso compartido de la caché
El almacenamiento en caché de prompts usa aislamiento a nivel de [espacio de trabajo](https://platform.claude.com/docs/es/manage-claude/workspaces). Las cachés están aisladas por espacio de trabajo, lo que garantiza la separación de datos entre espacios de trabajo dentro de la misma organización. Esto se aplica a la Claude API, Claude Platform on AWS y Microsoft Foundry; Bedrock y Google Cloud mantienen el aislamiento de caché a nivel de organización. Si usas varios espacios de trabajo, revisa tu estrategia de almacenamiento en caché para tener en cuenta esta diferencia.
* **Aislamiento por organización y espacio de trabajo:** Las cachés están aisladas entre organizaciones. Las distintas organizaciones nunca comparten cachés, incluso si usan prompts idénticos. Las cachés también están aisladas por espacio de trabajo dentro de una organización en la Claude API, Claude Platform on AWS y Microsoft Foundry; Bedrock y Google Cloud usan solo aislamiento a nivel de organización.
* **Coincidencia exacta:** Los aciertos de caché requieren segmentos de prompt 100% idénticos, incluidos todo el texto y las imágenes hasta el bloque marcado con control de caché, inclusive.
* **Generación de tokens de salida:** El almacenamiento en caché de prompts no tiene ningún efecto en la generación de tokens de salida. La respuesta que recibes es idéntica a la que obtendrías si no se usara el almacenamiento en caché de prompts.
### Mejores prácticas para un almacenamiento en caché eficaz
Para optimizar el rendimiento del almacenamiento en caché de prompts:
* Empieza con el [almacenamiento en caché automático](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#automatic-caching) para conversaciones de múltiples turnos. Gestiona los puntos de interrupción automáticamente.
* Usa [puntos de interrupción explícitos a nivel de bloque](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#explicit-cache-breakpoints) cuando necesites almacenar en caché diferentes secciones con distintas frecuencias de cambio.
* Almacena en caché contenido estable y reutilizable, como instrucciones del sistema, información de fondo, contextos grandes o definiciones de herramientas frecuentes.
* Coloca el contenido en caché al principio del prompt para obtener el mejor rendimiento.
* Usa los puntos de interrupción de caché de forma estratégica para separar diferentes secciones de prefijo almacenables en caché.
* Coloca el punto de interrupción en el último bloque que se mantiene idéntico entre solicitudes. Para un prompt con un prefijo estático y un sufijo variable (marcas de tiempo, contexto por solicitud, el mensaje entrante), ese es el final del prefijo, no el bloque variable.
* Analiza periódicamente las tasas de aciertos de caché y ajusta tu estrategia según sea necesario.
### Optimización para diferentes casos de uso
Adapta tu estrategia de almacenamiento en caché de prompts a tu escenario:
* Agentes conversacionales: Reduce el costo y la "latency" (latencia) en conversaciones extensas, especialmente aquellas con instrucciones largas o documentos cargados.
* Asistentes de programación: Mejora el autocompletado y las preguntas y respuestas sobre la base de código manteniendo en el prompt las secciones relevantes o una versión resumida de la base de código.
* Procesamiento de documentos grandes: Incorpora material extenso completo, incluidas 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 con precisión las respuestas de Claude. Los desarrolladores suelen incluir uno o dos ejemplos en el prompt, pero con el almacenamiento en caché de prompts puedes obtener un rendimiento aún mejor incluyendo más de 20 ejemplos diversos de respuestas de alta calidad.
* Uso de herramientas agéntico: Mejora el rendimiento en escenarios que implican múltiples llamadas a herramientas y cambios de código iterativos, donde cada paso normalmente requiere una nueva llamada a la API.
* Conversar con libros, artículos, documentación, transcripciones de podcasts y otro contenido extenso: Da vida a cualquier base de conocimiento incorporando el documento o los documentos completos en el prompt y permitiendo que los usuarios le hagan preguntas.
### Solución de problemas comunes
Si experimentas un comportamiento inesperado:
Con el [diagnóstico de caché](https://platform.claude.com/docs/es/build-with-claude/cache-diagnostics), la API compara solicitudes consecutivas e informa dónde divergió el prefijo del prompt, lo que resuelve automáticamente muchos de los pasos de esta lista.
* Asegúrate de que las secciones en caché sean idénticas entre llamadas. Para los puntos de interrupción explícitos, verifica que los marcadores `cache_control` estén en las mismas ubicaciones
* Comprueba que las llamadas se realicen dentro de la vida útil de la caché (5 minutos de forma predeterminada)
* Verifica que `tool_choice`, el uso de imágenes, la configuración de pensamiento y `output_config.effort` se mantengan consistentes entre llamadas
* Valida que estés almacenando en caché al menos el número mínimo de tokens para tu modelo y plataforma (consulta [Limitaciones de la caché](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#cache-limitations))
* Confirma que tu punto de interrupción esté en un bloque que se mantiene idéntico entre solicitudes. Las escrituras en caché ocurren solo en el punto de interrupción, y si ese bloque cambia (marcas de tiempo, contexto por solicitud, el mensaje entrante), el hash del prefijo nunca coincide. La retrospección no encuentra contenido estable detrás del punto de interrupción; solo encuentra entradas que solicitudes anteriores escribieron en sus propios puntos de interrupción
* Verifica que las claves de tus bloques de contenido `tool_use` tengan un orden estable, ya que algunos lenguajes (por ejemplo, Swift, Go) aleatorizan el orden de las claves durante la conversión a JSON, lo que rompe las cachés
* Usa el [diagnóstico de caché](https://platform.claude.com/docs/es/build-with-claude/cache-diagnostics) para que la API compare solicitudes consecutivas e informe qué parte del prompt divergió
Los cambios en `tool_choice` o la presencia/ausencia de imágenes en cualquier parte del prompt invalidarán la caché, lo que requerirá crear una nueva entrada de caché. Para obtener más detalles sobre la invalidación de la caché, consulta [Qué invalida la caché](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#what-invalidates-the-cache).
***
## Duración de caché de 1 hora
Si consideras que 5 minutos es muy poco tiempo, Anthropic también ofrece una duración de caché de 1 hora [con un costo adicional](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#pricing).
La duración de caché de 1 hora está disponible en la Claude API, [Amazon Bedrock](https://platform.claude.com/docs/es/build-with-claude/claude-in-amazon-bedrock), [Amazon Bedrock (Opus 4.6 y anteriores)](https://platform.claude.com/docs/es/build-with-claude/claude-on-amazon-bedrock-legacy), [Claude Platform on AWS](https://platform.claude.com/docs/es/build-with-claude/claude-platform-on-aws), [Google Cloud](https://platform.claude.com/docs/es/build-with-claude/claude-on-vertex-ai) y [Microsoft Foundry](https://platform.claude.com/docs/es/build-with-claude/claude-in-microsoft-foundry).
Para usar la caché extendida, incluye `ttl` en la definición de `cache_control` de esta manera:
```json
"cache_control": {
"type": "ephemeral",
"ttl": "1h"
}
```
La respuesta incluye información detallada de la caché como la siguiente:
```json Output
{
"usage": {
"input_tokens": 2048,
"cache_read_input_tokens": 1800,
"cache_creation_input_tokens": 248,
"output_tokens": 503,
"cache_creation": {
"ephemeral_5m_input_tokens": 148,
"ephemeral_1h_input_tokens": 100
}
}
}
```
Ten en cuenta que el campo actual `cache_creation_input_tokens` es igual a la suma de los valores del objeto `cache_creation`.
Si ves escrituras `ephemeral_5m_input_tokens` que no solicitaste mientras usas herramientas de servidor como la búsqueda web, consulta [Uso de herramientas con almacenamiento en caché de prompts](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-use-with-prompt-caching#server-tool-results-are-cached-automatically).
### Cuándo usar la caché de 1 hora
Si tienes prompts que se usan con una cadencia regular (es decir, indicaciones del sistema que se usan con más frecuencia que cada 5 minutos), sigue usando la caché de 5 minutos, ya que esta se seguirá actualizando sin cargo adicional.
La caché de 1 hora es más adecuada en los siguientes escenarios:
* Cuando tienes prompts que probablemente se usen con menos frecuencia que cada 5 minutos, pero con más frecuencia 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 después de 5 minutos.
* Cuando quieres mejorar el aprovechamiento de tu límite de velocidad, ya que los aciertos de caché no se descuentan de tu límite de velocidad.
La caché de 5 minutos y la de 1 hora se comportan igual en cuanto a latencia. Por lo general, verás una mejora en el tiempo hasta el primer token para documentos largos.
### Combinar diferentes TTL
Puedes usar controles de caché de 1 hora y de 5 minutos en la misma solicitud, pero con una restricción importante: las entradas de caché con un 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).
Al combinar TTL, la API determina tres ubicaciones de facturación en tu prompt:
1. Posición `A`: el recuento de tokens en el acierto de caché más alto (o 0 si no hay aciertos).
2. Posición `B`: el recuento de tokens en el bloque `cache_control` de 1 hora más alto después de `A` (o igual a `A` si no existe ninguno).
3. Posición `C`: el recuento de tokens en el último bloque `cache_control`.
Si `B` o `C` es mayor que `A`, necesariamente es un fallo de caché, porque `A` es el acierto de caché más alto.
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í tienes tres ejemplos. Esto representa los tokens de entrada de 3 solicitudes, cada una de las cuales tiene diferentes aciertos y fallos de caché. Como resultado, cada una tiene un precio calculado diferente, que se muestra en los recuadros de colores.
***
## Precalentar la caché
El "cache pre-warming" (precalentamiento de caché) te permite cargar tu indicación del sistema o tus definiciones de herramientas en la caché de prompts antes de que un usuario active una solicitud real. Esto elimina la penalización de latencia por fallo de caché en la primera interacción del usuario, reduciendo el "time-to-first-token" (tiempo hasta el primer token), o TTFT, en aplicaciones sensibles a la latencia.
### Cómo funciona
Establece `max_tokens: 0` en tu solicitud. La API lee tu prompt en el modelo y escribe la caché en cualquier "breakpoint" (punto de interrupción) de `cache_control`, y luego responde de inmediato sin generar ninguna salida. La respuesta tiene un arreglo `content` vacío, `stop_reason: "max_tokens"` y un bloque `usage` completamente poblado.
Coloca el punto de interrupción `cache_control` en el último bloque que se comparte con la solicitud posterior (normalmente tu indicación del sistema o tus definiciones de herramientas), no en el mensaje de usuario de relleno. De lo contrario, la entrada de caché queda asociada al mensaje de relleno y la solicitud posterior no la aprovechará. Usa también la misma configuración de pensamiento y el mismo `output_config.effort` que en tus solicitudes posteriores: esos valores se renderizan en el prompt (consulta [Qué invalida la caché](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#what-invalidates-the-cache)), por lo que un precalentamiento con una configuración diferente puede escribir una entrada que tu tráfico real nunca aprovecha. Esto implica usar un [punto de interrupción de caché explícito](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#explicit-cache-breakpoints) en lugar del [almacenamiento en caché automático](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#automatic-caching), ya que el almacenamiento en caché automático coloca el punto de interrupción en el último bloque, que aquí es el mensaje de relleno. El mensaje de usuario de relleno puede ser cualquier cadena con contenido que no sea solo espacios en blanco (los ejemplos aquí usan `"warmup"`); su contenido se lee en el modelo, pero nunca se responde.
Una solicitud de precalentamiento genera un cargo por **escritura en caché** si el prefijo aún no está en caché, igual que cualquier otra solicitud. Revisa `usage.cache_creation_input_tokens` en la respuesta para confirmar que se produjo una escritura. No se factura ningún token de salida.
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 0,
"system": [
{
"type": "text",
"text": "You are an expert software engineer with deep knowledge of distributed systems...",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [{"role": "user", "content": "warmup"}]
}'
```
```bash CLI
ant messages create \
--transform '{stop_reason,content,usage}' --format yaml <<'YAML'
model: claude-opus-5-5
max_tokens: 0
system:
- type: text
text: >-
You are an expert software engineer with deep knowledge of
distributed systems...
cache_control:
type: ephemeral
messages:
- role: user
content: warmup
YAML
```
```python Python
client = anthropic.Anthropic()
# Ejecuta esto antes de que lleguen los usuarios para precalentar la caché compartida de la indicación del sistema.
prewarm = client.messages.create(
model="claude-opus-5-5",
max_tokens=0,
system=[
{
"type": "text",
"text": "You are an expert software engineer with deep knowledge of distributed systems...",
"cache_control": {"type": "ephemeral"},
}
],
messages=[{"role": "user", "content": "warmup"}],
)
print(prewarm.stop_reason) # "max_tokens"
print(prewarm.content) # []
print(prewarm.usage)
```
```typescript TypeScript
const client = new Anthropic();
// Ejecuta esto antes de que lleguen los usuarios para precalentar la caché compartida de la indicación del sistema.
const prewarm = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 0,
system: [
{
type: "text",
text: "You are an expert software engineer with deep knowledge of distributed systems...",
cache_control: { type: "ephemeral" }
}
],
messages: [{ role: "user", content: "warmup" }]
});
console.log(prewarm.stop_reason); // "max_tokens"
console.log(prewarm.content); // []
console.log(prewarm.usage);
```
```csharp C#
AnthropicClient client = new();
var prewarm = await client.Messages.Create(
new()
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 0,
System = new(
[
new TextBlockParam
{
Text = "You are an expert software engineer with deep knowledge of distributed systems...",
CacheControl = new(),
},
]
),
Messages = [new() { Role = Role.User, Content = "warmup" }],
}
);
Console.WriteLine(prewarm.StopReason?.Raw()); // "max_tokens"
Console.WriteLine(prewarm.Content.Count); // 0
Console.WriteLine(prewarm.Usage);
```
```go Go
client := anthropic.NewClient()
prewarm, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 0,
System: []anthropic.TextBlockParam{
{
Text: "You are an expert software engineer with deep knowledge of distributed systems...",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("warmup")),
},
})
if err != nil {
panic(err)
}
fmt.Println(prewarm.StopReason) // "max_tokens"
fmt.Println(prewarm.Content) // []
fmt.Println(prewarm.Usage.RawJSON())
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
Message prewarm = client.messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(0)
.systemOfTextBlockParams(List.of(TextBlockParam.builder()
.text("You are an expert software engineer with deep knowledge of distributed systems...")
.cacheControl(CacheControlEphemeral.builder().build())
.build()))
.addUserMessage("warmup")
.build());
IO.println(prewarm.stopReason()); // Optional[max_tokens]
IO.println(prewarm.content()); // []
IO.println(prewarm.usage());
```
```php PHP
$client = new Client();
$prewarm = $client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 0,
system: [
[
'type' => 'text',
'text' => 'You are an expert software engineer with deep knowledge of distributed systems...',
'cache_control' => ['type' => 'ephemeral'],
],
],
messages: [['role' => 'user', 'content' => 'warmup']],
);
echo $prewarm->stopReason, PHP_EOL; // "max_tokens"
echo json_encode($prewarm->content), PHP_EOL; // []
echo json_encode($prewarm->usage), PHP_EOL;
```
```ruby Ruby
client = Anthropic::Client.new
prewarm = client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 0,
system_: [
{
type: "text",
text: "You are an expert software engineer with deep knowledge of distributed systems...",
cache_control: {type: "ephemeral"}
}
],
messages: [{role: "user", content: "warmup"}]
)
puts prewarm.stop_reason # :max_tokens
puts prewarm.content # []
puts prewarm.usage
```
La API devuelve un arreglo `content` vacío:
```json Output
{
"id": "msg_01XFDUDYJgAACzvnptvVoYEL",
"type": "message",
"role": "assistant",
"content": [],
"model": "claude-opus-5-5",
"stop_reason": "max_tokens",
"stop_sequence": null,
"usage": {
"input_tokens": 8,
"cache_creation_input_tokens": 5120,
"cache_read_input_tokens": 0,
"cache_creation": {
"ephemeral_5m_input_tokens": 5120,
"ephemeral_1h_input_tokens": 0
},
"iterations": [
{
"input_tokens": 8,
"output_tokens": 0,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 5120,
"cache_creation": {
"ephemeral_5m_input_tokens": 5120,
"ephemeral_1h_input_tokens": 0
},
"type": "message"
}
],
"output_tokens": 0,
"service_tier": "standard",
"inference_geo": "global"
}
}
```
### Patrón de uso típico
Lanza una solicitud de precalentamiento cuando se inicie tu aplicación (o en un intervalo programado) y luego envía las solicitudes reales de los usuarios una vez que el precalentamiento haya terminado:
```bash cURL
# Precalienta la caché al iniciar la aplicación o en un intervalo programado.
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 0,
"system": [
{
"type": "text",
"text": "You are an expert software engineer with deep knowledge of distributed systems...",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [{"role": "user", "content": "warmup"}]
}'
# Después, cuando el usuario envía un mensaje, el prefijo de la indicación del sistema ya está en caché.
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"system": [
{
"type": "text",
"text": "You are an expert software engineer with deep knowledge of distributed systems...",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [{"role": "user", "content": "How do I implement a binary search tree?"}]
}'
```
```bash CLI
# Precalienta la caché al iniciar la aplicación o en un intervalo programado.
ant messages create --transform usage <<'YAML'
model: claude-opus-5-5
max_tokens: 0
system:
- type: text
text: >-
You are an expert software engineer with deep knowledge of
distributed systems...
cache_control:
type: ephemeral
messages:
- role: user
content: warmup
YAML
# Después, cuando el usuario envía un mensaje, el prefijo de la indicación del sistema ya está en caché.
ant messages create --transform 'content.#(type=="text").text' --raw-output <<'YAML'
model: claude-opus-5-5
max_tokens: 1024
system:
- type: text
text: >-
You are an expert software engineer with deep knowledge of
distributed systems...
cache_control:
type: ephemeral
messages:
- role: user
content: How do I implement a binary search tree?
YAML
```
```python Python
client = anthropic.Anthropic()
SYSTEM_PROMPT = [
{
"type": "text",
"text": "You are an expert software engineer with deep knowledge of distributed systems...",
"cache_control": {"type": "ephemeral"},
}
]
def prewarm_cache() -> None:
"""Call this at application startup or on a scheduled interval."""
client.messages.create(
model="claude-opus-5-5",
max_tokens=0,
system=SYSTEM_PROMPT,
messages=[{"role": "user", "content": "warmup"}],
)
def respond(user_message: str) -> anthropic.types.Message:
"""The real user request; benefits from a warm cache."""
return client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
system=SYSTEM_PROMPT,
messages=[{"role": "user", "content": user_message}],
)
# Precalienta la caché antes de que llegue tráfico de usuarios.
prewarm_cache()
# Después, cuando el usuario envía un mensaje, el prefijo de la indicación del sistema ya está en caché.
response = respond("How do I implement a binary search tree?")
for block in response.content:
if block.type == "text":
print(block.text)
```
```typescript TypeScript
const client = new Anthropic();
const SYSTEM_PROMPT: Anthropic.TextBlockParam[] = [
{
type: "text",
text: "You are an expert software engineer with deep knowledge of distributed systems...",
cache_control: { type: "ephemeral" }
}
];
// Llama a esto al iniciar la aplicación o en un intervalo programado.
async function prewarmCache(): Promise {
await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 0,
system: SYSTEM_PROMPT,
messages: [{ role: "user", content: "warmup" }]
});
}
// La solicitud real del usuario; se beneficia de una caché precalentada.
async function respond(userMessage: string): Promise {
return client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
system: SYSTEM_PROMPT,
messages: [{ role: "user", content: userMessage }]
});
}
// Precalienta la caché antes de que llegue tráfico de usuarios.
await prewarmCache();
// Después, cuando el usuario envía un mensaje, el prefijo de la indicación del sistema ya está en caché.
const response = await respond("How do I implement a binary search tree?");
const textBlock = response.content.find(
(block): block is Anthropic.TextBlock => block.type === "text"
);
console.log(textBlock?.text);
```
```csharp C#
AnthropicClient client = new();
List systemPrompt =
[
new TextBlockParam
{
Text = "You are an expert software engineer with deep knowledge of distributed systems...",
CacheControl = new(),
},
];
// Llama a esto al iniciar la aplicación o en un intervalo programado.
async Task PrewarmCache() =>
await client.Messages.Create(
new()
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 0,
System = new(systemPrompt),
Messages = [new() { Role = Role.User, Content = "warmup" }],
}
);
// La solicitud real del usuario; se beneficia de una caché precalentada.
async Task Respond(string userMessage) =>
await client.Messages.Create(
new()
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
System = new(systemPrompt),
Messages = [new() { Role = Role.User, Content = userMessage }],
}
);
// Precalienta la caché antes de que llegue cualquier tráfico de usuarios.
await PrewarmCache();
// Más tarde, cuando el usuario envía un mensaje, el prefijo de la indicación del sistema ya está en caché.
var response = await Respond("How do I implement a binary search tree?");
foreach (var block in response.Content)
{
if (block.TryPickText(out var textBlock))
{
Console.WriteLine(textBlock.Text);
}
}
```
```go Go
var client = anthropic.NewClient()
var systemPrompt = []anthropic.TextBlockParam{
{
Text: "You are an expert software engineer with deep knowledge of distributed systems...",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
}
// Llama a esto al iniciar la aplicación o en un intervalo programado.
func prewarmCache() error {
_, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 0,
System: systemPrompt,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("warmup")),
},
})
return err
}
// La solicitud real del usuario; se beneficia de una caché precalentada.
func respond(userMessage string) (*anthropic.Message, error) {
return client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
System: systemPrompt,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock(userMessage)),
},
})
}
func main() {
// Precalienta la caché antes de que llegue tráfico de usuarios.
if err := prewarmCache(); err != nil {
log.Fatal(err)
}
// Después, cuando el usuario envía un mensaje, el prefijo de la indicación del sistema ya está en caché.
response, err := respond("How do I implement a binary search tree?")
if err != nil {
log.Fatal(err)
}
for _, block := range response.Content {
if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {
fmt.Println(textBlock.Text)
}
}
}
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
List systemPrompt = List.of(TextBlockParam.builder()
.text("You are an expert software engineer with deep knowledge of distributed systems...")
.cacheControl(CacheControlEphemeral.builder().build())
.build());
// Llama a esto al iniciar la aplicación o en un intervalo programado.
void prewarmCache() {
client.messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(0)
.systemOfTextBlockParams(systemPrompt)
.addUserMessage("warmup")
.build());
}
// La solicitud real del usuario; se beneficia de una caché precalentada.
Message respond(String userMessage) {
return client.messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.systemOfTextBlockParams(systemPrompt)
.addUserMessage(userMessage)
.build());
}
void main() {
// Precalienta la caché antes de que llegue tráfico de usuarios.
prewarmCache();
// Después, cuando el usuario envía un mensaje, el prefijo de la indicación del sistema ya está en caché.
Message response = respond("How do I implement a binary search tree?");
response.content().stream()
.flatMap(block -> block.text().stream())
.forEach(textBlock -> IO.println(textBlock.text()));
}
```
```php PHP
$client = new Client();
$systemPrompt = [
[
'type' => 'text',
'text' => 'You are an expert software engineer with deep knowledge of distributed systems...',
'cache_control' => ['type' => 'ephemeral'],
],
];
// Llama a esto al iniciar la aplicación o en un intervalo programado.
$prewarmCache = fn () => $client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 0,
system: $systemPrompt,
messages: [['role' => 'user', 'content' => 'warmup']],
);
// La solicitud real del usuario; se beneficia de una caché precalentada.
$respond = fn (string $userMessage) => $client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 1024,
system: $systemPrompt,
messages: [['role' => 'user', 'content' => $userMessage]],
);
// Precalienta la caché antes de que llegue tráfico de usuarios.
$prewarmCache();
// Después, cuando el usuario envía un mensaje, el prefijo de la indicación del sistema ya está en caché.
$response = $respond('How do I implement a binary search tree?');
foreach ($response->content as $block) {
if ($block->type === 'text') {
echo $block->text, PHP_EOL;
}
}
```
```ruby Ruby
client = Anthropic::Client.new
SYSTEM_PROMPT = [
{
type: "text",
text: "You are an expert software engineer with deep knowledge of distributed systems...",
cache_control: {type: "ephemeral"}
}
]
# Llama a esto al iniciar la aplicación o en un intervalo programado.
def prewarm_cache(client)
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 0,
system_: SYSTEM_PROMPT,
messages: [{role: "user", content: "warmup"}]
)
end
# La solicitud real del usuario; se beneficia de una caché precalentada.
def respond(client, user_message)
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
system_: SYSTEM_PROMPT,
messages: [{role: "user", content: user_message}]
)
end
# Precalienta la caché antes de que llegue tráfico de usuarios.
prewarm_cache(client)
# Después, cuando el usuario envía un mensaje, el prefijo de la indicación del sistema ya está en caché.
response = respond(client, "How do I implement a binary search tree?")
response.content.each do |block|
puts block.text if block.type == :text
end
```
Ten en cuenta que el TTL de la caché sigue aplicándose. Para la caché predeterminada de 5 minutos, envía una nueva solicitud de precalentamiento al menos cada 5 minutos para mantener la caché caliente. Para intervalos más largos entre solicitudes de usuarios, usa en su lugar la [duración de caché de 1 hora](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#1-hour-cache-duration).
### Limitaciones
Una solicitud con `max_tokens: 0` se rechaza con un `invalid_request_error` si se establece cualquiera de los siguientes, ya que cada uno implica una salida que un presupuesto de cero tokens no puede producir:
* `stream: true`
* [Pensamiento extendido](https://platform.claude.com/docs/es/build-with-claude/extended-thinking) (`thinking.type: "enabled"`)
* [Salidas estructuradas](https://platform.claude.com/docs/es/build-with-claude/structured-outputs) (`output_config.format`)
* `tool_choice` de `{"type": "tool", ...}` o `{"type": "any"}`
`max_tokens: 0` también se rechaza dentro de una solicitud de [Message Batches](https://platform.claude.com/docs/es/build-with-claude/batch-processing). El precalentamiento está orientado al tiempo hasta el primer token, que no aplica al procesamiento por lotes, y una entrada de caché escrita durante el procesamiento por lotes probablemente expiraría antes de que se ejecute la solicitud posterior.
### Reemplazar la solución alternativa de max\_tokens=1
Antes de que `max_tokens: 0` estuviera disponible, algunas aplicaciones usaban llamadas de calentamiento con `max_tokens: 1` para lograr el mismo efecto. Se prefiere el enfoque de `max_tokens: 0`: no se produce ninguna salida, por lo que no hay una respuesta de un solo token que descartar, no se factura ningún token de salida y la intención de la solicitud es inequívoca.
***
## Ejemplos de almacenamiento en caché de prompts
Para ayudarte a comenzar con el "prompt caching" (almacenamiento en caché de prompts), el [cookbook de almacenamiento en caché de prompts](https://platform.claude.com/cookbook/misc-prompt-caching) ofrece ejemplos detallados y buenas prácticas.
Los siguientes fragmentos de código muestran varios patrones de almacenamiento en caché de prompts. Estos ejemplos demuestran cómo implementar el almacenamiento en caché en diferentes escenarios, ayudándote a comprender las aplicaciones prácticas de esta función:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-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?"
}
]
}'
```
```bash CLI
ant messages create --transform usage <<'YAML'
model: claude-opus-5-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?
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-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?",
}
],
)
print(response.usage.model_dump_json())
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-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?"
}
]
});
console.log(response.usage);
```
```csharp C#
AnthropicClient client = new()
{
ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
};
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
System = new MessageCreateParamsSystem(new List
{
new TextBlockParam()
{
Text = "You are an AI assistant tasked with analyzing legal documents.",
},
new TextBlockParam()
{
Text = "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
CacheControl = new CacheControlEphemeral(),
},
}),
Messages =
[
new()
{
Role = Role.User,
Content = "What are the key terms and conditions in this agreement?"
}
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message.Usage);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
System: []anthropic.TextBlockParam{
{
Text: "You are an AI assistant tasked with analyzing legal documents.",
},
{
Text: "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("What are the key terms and conditions in this agreement?")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Usage.RawJSON())
```
```java Java
import com.anthropic.models.messages.CacheControlEphemeral;
// ...
public class LegalDocumentAnalysisExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.systemOfTextBlockParams(
List.of(
TextBlockParam.builder()
.text("You are an AI assistant tasked with analyzing legal documents.")
.build(),
TextBlockParam.builder()
.text(
"Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]"
)
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
)
.addUserMessage("What are the key terms and conditions in this agreement?")
.build();
Message message = client.messages().create(params);
System.out.println(message.usage());
}
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 1024,
messages: [
[
'role' => 'user',
'content' => 'What are the key terms and conditions in this agreement?'
]
],
model: 'claude-opus-5-5',
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']
]
],
);
echo json_encode($message->usage), PHP_EOL;
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-5-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?"
}
]
)
puts message.usage
```
Este ejemplo demuestra el uso básico del almacenamiento en caché de prompts, almacenando en caché el texto completo del acuerdo legal como prefijo mientras la instrucción del usuario se mantiene sin almacenar en caché.
Para la primera solicitud:
* `input_tokens`: número de tokens solo en el mensaje del usuario
* `cache_creation_input_tokens`: número de tokens en todo el mensaje del sistema, incluido el documento legal
* `cache_read_input_tokens`: 0 (no hay acierto de caché en la primera solicitud)
Para las solicitudes posteriores dentro de la vida útil de la caché:
* `input_tokens`: número de tokens solo en el mensaje del usuario
* `cache_creation_input_tokens`: 0 (no se crea nueva caché)
* `cache_read_input_tokens`: número de tokens en todo el mensaje del sistema almacenado en caché
Las definiciones de herramientas se pueden almacenar en caché colocando `cache_control` en la última herramienta de tu arreglo `tools`. Todas las herramientas definidas antes de esa herramienta, incluida ella misma, se almacenan en caché como un único prefijo.
```json
{
"model": "claude-opus-5-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" } },
"required": ["location"]
}
},
{
"name": "get_time",
"description": "Get the current time in a given time zone",
"input_schema": {
"type": "object",
"properties": { "timezone": { "type": "string" } },
"required": ["timezone"]
},
"cache_control": { "type": "ephemeral" }
}
],
"messages": [{ "role": "user", "content": "What is the weather and time in New York?" }]
}
```
En la primera solicitud, `cache_creation_input_tokens` refleja el recuento de tokens de todas las definiciones de herramientas. En las solicitudes posteriores dentro de la vida útil de la caché, esos tokens aparecen en `cache_read_input_tokens`.
Para conocer en detalle la interacción entre las definiciones de herramientas, `defer_loading` y la invalidación de la caché, consulta [Uso de herramientas con almacenamiento en caché de prompts](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-use-with-prompt-caching).
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-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"}
}
]
}
]
}'
```
```bash CLI
ant messages create --transform usage <<'YAML'
model: claude-opus-5-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
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
system=[
{
"type": "text",
"text": "...long system prompt",
"cache_control": {"type": "ephemeral"},
}
],
messages=[
# ...conversación larga hasta ahora
{
"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'd 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"},
},
],
},
],
)
print(response.usage.model_dump_json())
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
system: [
{
type: "text",
text: "...long system prompt",
cache_control: { type: "ephemeral" }
}
],
messages: [
// ...conversación larga hasta ahora
{
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'd 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" }
}
]
}
]
});
console.log(response.usage);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
System = new MessageCreateParamsSystem(new List
{
new TextBlockParam()
{
Text = "...long system prompt",
CacheControl = new CacheControlEphemeral(),
},
}),
Messages =
[
new()
{
Role = Role.User,
Content = new MessageParamContent(new List
{
new ContentBlockParam(new TextBlockParam("Hello, can you tell me more about the solar system?")),
}),
},
new()
{
Role = 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?"
},
new()
{
Role = Role.User,
Content = new MessageParamContent(new List
{
new ContentBlockParam(new TextBlockParam("Good to know.")),
new ContentBlockParam(new TextBlockParam()
{
Text = "Tell me more about Mars.",
CacheControl = new CacheControlEphemeral(),
}),
})
}
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message.Usage);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
System: []anthropic.TextBlockParam{
{
Text: "...long system prompt",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, can you tell me more about the solar system?")),
anthropic.NewAssistantMessage(anthropic.NewTextBlock("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: anthropic.MessageParamRoleUser,
Content: []anthropic.ContentBlockParamUnion{
anthropic.NewTextBlock("Good to know."),
{OfText: &anthropic.TextBlockParam{
Text: "Tell me more about Mars.",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
}},
},
},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Usage.RawJSON())
```
```java Java
import com.anthropic.models.messages.CacheControlEphemeral;
// ...
public class ConversationWithCacheControlExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Crea una indicación del sistema efímera
TextBlockParam systemPrompt = TextBlockParam.builder()
.text("...long system prompt")
.cacheControl(CacheControlEphemeral.builder().build())
.build();
// Crea los parámetros del mensaje
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.systemOfTextBlockParams(List.of(systemPrompt))
// Primer mensaje del usuario (sin control de caché)
.addUserMessage("Hello, can you tell me more about the solar system?")
// Respuesta del asistente
.addAssistantMessage(
"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?"
)
// Segundo mensaje del usuario (con control de caché)
.addUserMessageOfBlockParams(
List.of(
ContentBlockParam.ofText(TextBlockParam.builder().text("Good to know.").build()),
ContentBlockParam.ofText(
TextBlockParam.builder()
.text("Tell me more about Mars.")
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
)
)
.build();
Message message = client.messages().create(params);
System.out.println(message.usage());
}
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 1024,
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']
]
]
]
],
model: 'claude-opus-5-5',
system: [
[
'type' => 'text',
'text' => '...long system prompt',
'cache_control' => ['type' => 'ephemeral']
]
],
);
echo json_encode($message->usage), PHP_EOL;
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-5-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" }
}
]
}
]
)
puts message.usage
```
Este ejemplo demuestra cómo usar el almacenamiento en caché de prompts en una conversación de varios turnos.
En cada turno, el bloque final del mensaje final se marca con `cache_control` para que la conversación pueda almacenarse en caché de forma incremental. El sistema busca y usa automáticamente la secuencia de bloques previamente almacenada en caché más larga para los mensajes posteriores. Es decir, los bloques que antes se marcaron con un bloque `cache_control` después ya no se marcan así, pero aun así se considerarán un acierto de caché (¡y también una actualización de la caché!) si se aprovechan dentro de 5 minutos.
Además, observa que el parámetro `cache_control` se coloca en el mensaje del sistema. Esto es para garantizar que, si se expulsa de la caché (tras no usarse durante más de 5 minutos), se vuelva a agregar a la caché en la siguiente solicitud.
Este enfoque es útil para mantener el contexto en conversaciones en curso sin procesar repetidamente la misma información.
Cuando esto está configurado correctamente, deberías ver lo siguiente en la respuesta de uso de cada solicitud:
* `input_tokens`: número de tokens en el nuevo mensaje del usuario (será mínimo)
* `cache_creation_input_tokens`: número de tokens en los nuevos turnos del asistente y del usuario
* `cache_read_input_tokens`: número de tokens en la conversación hasta el turno anterior
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-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"}
}
]
}
]
}'
```
```bash CLI
ant messages create --transform usage <<'YAML'
model: claude-opus-5-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.
# Instructions
- Always search for relevant documents before answering
- Provide citations for your sources
- Be objective and accurate in your responses
- If multiple documents contain relevant information, synthesize them
- Acknowledge when information is not available in the knowledge base
cache_control:
type: ephemeral
- type: text
text: |-
# Knowledge Base Context
Here are the relevant documents for this conversation:
## Document 1: Solar System Overview
The solar system consists of the Sun and all objects that orbit it...
## Document 2: Planetary Characteristics
Each planet has unique features. Mercury is the smallest planet...
## Document 3: Mars Exploration
Mars has been a target of exploration for decades...
[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
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-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"},
}
],
},
],
)
print(response.usage.model_dump_json())
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-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" }
}
]
}
]
});
console.log(response.usage);
```
```csharp C#
AnthropicClient client = new()
{
ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
};
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Tools =
[
new ToolUnion(new Tool()
{
Name = "search_documents",
Description = "Search through the knowledge base",
InputSchema = new InputSchema()
{
Properties = new Dictionary
{
["query"] = JsonSerializer.SerializeToElement(new { type = "string", description = "Search query" }),
},
Required = ["query"],
},
}),
new ToolUnion(new Tool()
{
Name = "get_document",
Description = "Retrieve a specific document by ID",
InputSchema = new InputSchema()
{
Properties = new Dictionary
{
["doc_id"] = JsonSerializer.SerializeToElement(new { type = "string", description = "Document ID" }),
},
Required = ["doc_id"],
},
CacheControl = new CacheControlEphemeral(),
}),
],
System = new MessageCreateParamsSystem(new List
{
new TextBlockParam()
{
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",
CacheControl = new CacheControlEphemeral(),
},
new TextBlockParam()
{
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...]",
CacheControl = new CacheControlEphemeral(),
},
}),
Messages =
[
new() { Role = Role.User, Content = "Can you search for information about Mars rovers?" },
new()
{
Role = Role.Assistant,
Content = new MessageParamContent(new List
{
new ContentBlockParam(new ToolUseBlockParam()
{
ID = "tool_1",
Name = "search_documents",
Input = new Dictionary
{
["query"] = JsonSerializer.SerializeToElement("Mars rovers"),
},
}),
}),
},
new()
{
Role = Role.User,
Content = new MessageParamContent(new List
{
new ContentBlockParam(new ToolResultBlockParam()
{
ToolUseID = "tool_1",
Content = "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",
}),
}),
},
new()
{
Role = Role.Assistant,
Content = "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.",
},
new()
{
Role = Role.User,
Content = new MessageParamContent(new List
{
new ContentBlockParam(new TextBlockParam()
{
Text = "Yes, please tell me about the Perseverance rover specifically.",
CacheControl = new CacheControlEphemeral(),
}),
}),
},
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message.Usage);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Tools: []anthropic.ToolUnionParam{
{OfTool: &anthropic.ToolParam{
Name: "search_documents",
Description: anthropic.String("Search through the knowledge base"),
InputSchema: anthropic.ToolInputSchemaParam{
Properties: map[string]any{
"query": map[string]any{
"type": "string",
"description": "Search query",
},
},
Required: []string{"query"},
},
}},
{OfTool: &anthropic.ToolParam{
Name: "get_document",
Description: anthropic.String("Retrieve a specific document by ID"),
InputSchema: anthropic.ToolInputSchemaParam{
Properties: map[string]any{
"doc_id": map[string]any{
"type": "string",
"description": "Document ID",
},
},
Required: []string{"doc_id"},
},
CacheControl: anthropic.NewCacheControlEphemeralParam(),
}},
},
System: []anthropic.TextBlockParam{
{
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",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
{
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...]",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Can you search for information about Mars rovers?")),
anthropic.NewAssistantMessage(anthropic.NewToolUseBlock(
"tool_1",
map[string]any{"query": "Mars rovers"},
"search_documents",
)),
anthropic.NewUserMessage(anthropic.NewToolResultBlock(
"tool_1",
"Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",
false,
)),
anthropic.NewAssistantMessage(anthropic.NewTextBlock("I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.")),
{
Role: anthropic.MessageParamRoleUser,
Content: []anthropic.ContentBlockParamUnion{
{OfText: &anthropic.TextBlockParam{
Text: "Yes, please tell me about the Perseverance rover specifically.",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
}},
},
},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Usage.RawJSON())
```
```java Java
import com.anthropic.models.messages.CacheControlEphemeral;
// ...
public class MultipleCacheBreakpointsExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Esquema de la herramienta de búsqueda
InputSchema searchSchema = InputSchema.builder()
.properties(
JsonValue.from(
Map.of("query", Map.of("type", "string", "description", "Search query"))
)
)
.putAdditionalProperty("required", JsonValue.from(List.of("query")))
.build();
// Esquema de la herramienta para obtener documentos
InputSchema getDocSchema = InputSchema.builder()
.properties(
JsonValue.from(
Map.of("doc_id", Map.of("type", "string", "description", "Document ID"))
)
)
.putAdditionalProperty("required", JsonValue.from(List.of("doc_id")))
.build();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
// Herramientas con control de caché en la última
.addTool(
Tool.builder()
.name("search_documents")
.description("Search through the knowledge base")
.inputSchema(searchSchema)
.build()
)
.addTool(
Tool.builder()
.name("get_document")
.description("Retrieve a specific document by ID")
.inputSchema(getDocSchema)
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
// Indicaciones del sistema con control de caché en instrucciones y contexto por separado
.systemOfTextBlockParams(
List.of(
TextBlockParam.builder()
.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"
)
.cacheControl(CacheControlEphemeral.builder().build())
.build(),
TextBlockParam.builder()
.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...]"
)
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
)
// Historial de la conversación
.addUserMessage("Can you search for information about Mars rovers?")
.addAssistantMessageOfBlockParams(
List.of(
ContentBlockParam.ofToolUse(
ToolUseBlockParam.builder()
.id("tool_1")
.name("search_documents")
.input(JsonValue.from(Map.of("query", "Mars rovers")))
.build()
)
)
)
.addUserMessageOfBlockParams(
List.of(
ContentBlockParam.ofToolResult(
ToolResultBlockParam.builder()
.toolUseId("tool_1")
.content(
"Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)"
)
.build()
)
)
)
.addAssistantMessageOfBlockParams(
List.of(
ContentBlockParam.ofText(
TextBlockParam.builder()
.text(
"I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document."
)
.build()
)
)
)
.addUserMessageOfBlockParams(
List.of(
ContentBlockParam.ofText(
TextBlockParam.builder()
.text("Yes, please tell me about the Perseverance rover specifically.")
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
)
)
.build();
Message message = client.messages().create(params);
System.out.println(message.usage());
}
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 1024,
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']
]
]
]
],
model: 'claude-opus-5-5',
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']
]
],
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']
]
],
);
echo json_encode($message->usage), PHP_EOL;
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-5-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" }
}
]
}
]
)
puts message.usage
```
Este ejemplo completo demuestra cómo usar los 4 puntos de interrupción de caché disponibles para optimizar diferentes partes de tu prompt:
1. **Caché de herramientas** (punto de interrupción de caché 1): el parámetro `cache_control` en la última definición de herramienta almacena en caché todas las definiciones de herramientas.
2. **Caché de instrucciones reutilizables** (punto de interrupción de caché 2): las instrucciones estáticas de la indicación del sistema se almacenan en caché por separado. Estas instrucciones rara vez cambian entre solicitudes.
3. **Caché de contexto RAG** (punto de interrupción de caché 3): los documentos de la base de conocimiento se almacenan en caché de forma independiente, lo que te permite actualizar los documentos RAG sin invalidar la caché de herramientas o de instrucciones.
4. **Caché del historial de conversación** (punto de interrupción de caché 4): el mensaje final del usuario se marca con `cache_control` para habilitar el almacenamiento en caché incremental de la conversación a medida que avanza.
Este enfoque ofrece la máxima flexibilidad:
* Si agregas un nuevo turno a la conversación sin cambiar el contenido anterior, se reutilizan los cuatro segmentos de caché
* Si actualizas los documentos RAG pero mantienes las mismas herramientas e instrucciones, se reutilizan los dos primeros segmentos de caché
* Si cambias la conversación pero mantienes las mismas herramientas, instrucciones y documentos, se reutilizan los tres primeros segmentos
* Los cambios en cualquier punto de interrupción invalidan ese segmento y todo lo que viene después, mientras que los segmentos almacenados en caché anteriores siguen siendo válidos
Para la primera solicitud:
* `input_tokens`: mínimo (tokens después del último punto de interrupción de caché, cerca de 0 en este ejemplo)
* `cache_creation_input_tokens`: tokens en todos los segmentos almacenados en caché (herramientas + instrucciones + documentos RAG + historial de conversación)
* `cache_read_input_tokens`: 0 (no hay aciertos de caché)
Para las solicitudes posteriores con solo un nuevo mensaje del usuario (y el cuarto punto de interrupción movido a ese nuevo mensaje final, como en el ejemplo):
* `input_tokens`: mínimo (tokens después del último punto de interrupción de caché, cerca de 0 en este ejemplo)
* `cache_creation_input_tokens`: tokens en el nuevo mensaje del usuario y en el turno anterior del asistente (el nuevo segmento de conversación que se almacena en caché)
* `cache_read_input_tokens`: todos los tokens previamente almacenados en caché (herramientas + instrucciones + documentos RAG + conversación anterior)
Este patrón es especialmente potente para:
* Aplicaciones RAG con contextos de documentos grandes
* Sistemas de agentes que usan múltiples herramientas
* Conversaciones de larga duración que necesitan mantener el contexto
* Aplicaciones que necesitan optimizar diferentes partes del prompt de forma independiente
## Retención de datos
El almacenamiento en caché de prompts (tanto automático como explícito) es apto para "zero data retention" (retención de datos cero), o ZDR. Anthropic no almacena el texto sin procesar de tus prompts ni de las respuestas de Claude.
Las representaciones de caché KV (clave-valor) y los hashes criptográficos del contenido almacenado en caché se mantienen solo en memoria y no se almacenan en reposo. Las entradas almacenadas en caché tienen una vida útil mínima de 5 minutos (estándar) o 1 hora (extendida), tras la cual se eliminan con prontitud, aunque no de inmediato. Las entradas de caché están aisladas entre organizaciones y, en la Claude API, Claude Platform on AWS y Microsoft Foundry, entre espacios de trabajo dentro de una organización.
Para conocer la aptitud para ZDR de todas las funciones, consulta [API y retención de datos](https://platform.claude.com/docs/es/manage-claude/api-and-data-retention).
***
## Preguntas frecuentes
**En la mayoría de los casos, basta con un único punto de interrupción de caché al final de tu contenido estático.** Las escrituras en caché ocurren solo en el bloque que marcas. Colócalo en el último bloque que se mantiene idéntico entre solicitudes, y cada solicitud posterior leerá esa misma entrada. Si un bloque posterior varía en cada solicitud (una marca de tiempo, el mensaje entrante), mantén el punto de interrupción antes de él, en el último bloque estable.
Solo necesitas múltiples puntos de interrupción si:
* Una conversación creciente desplaza tu punto de interrupción 20 o más bloques más allá de la última escritura en caché, dejando la entrada anterior fuera de la ventana de búsqueda retrospectiva
* Quieres almacenar en caché de forma independiente secciones que se actualizan con diferentes frecuencias
* Necesitas un control explícito sobre lo que se almacena en caché para optimizar costos
Ejemplo: si tienes instrucciones del sistema (que rara vez cambian) y contexto RAG (que cambia a diario), podrías usar dos puntos de interrupción para almacenarlos en caché por separado.
No, los puntos de interrupción de caché en sí son gratuitos. Solo pagas por:
* Escribir contenido en la caché (25 % más que los tokens de entrada base para un TTL de 5 minutos)
* Leer de la caché (una fracción del precio base de los tokens de entrada; consulta [Precios](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#pricing))
* Tokens de entrada normales para el contenido no almacenado en caché
La cantidad de puntos de interrupción no afecta el precio; solo importa la cantidad de contenido almacenado en caché y leído.
La respuesta de uso incluye tres campos separados de tokens de entrada que, en conjunto, representan tu entrada total:
```text wrap
total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens
```
* `cache_read_input_tokens`: tokens recuperados de la caché (todo lo anterior a los puntos de interrupción de caché que estaba almacenado en caché)
* `cache_creation_input_tokens`: tokens nuevos que se escriben en la caché (en los puntos de interrupción de caché)
* `input_tokens`: tokens **después del último punto de interrupción de caché** que no están almacenados en caché
**Importante:** `input_tokens` NO representa todos los tokens de entrada, solo la parte posterior a tu último punto de interrupción de caché. Si tienes contenido almacenado en caché, `input_tokens` normalmente será mucho menor que tu entrada total.
**Ejemplo:** con un documento de 200k tokens almacenado en caché y una pregunta del usuario de 50 tokens:
* `cache_read_input_tokens`: 200,000
* `cache_creation_input_tokens`: 0
* `input_tokens`: 50
* **Total:** 200,050 tokens
Este desglose es fundamental para comprender tanto tus costos como el uso de tu "rate limit" (límite de velocidad). Consulta [Seguimiento del rendimiento de la caché](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#tracking-cache-performance) para obtener más detalles.
La vida útil mínima predeterminada de la caché (TTL) es de 5 minutos. Esta vida útil se renueva cada vez que se usa el contenido almacenado en caché.
Si consideras que 5 minutos es muy poco, Anthropic también ofrece un [TTL de caché de 1 hora](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#1-hour-cache-duration).
La vida útil se mide desde el inicio de la solicitud que escribe o lee la entrada de caché, no desde el final de su respuesta. El tiempo dedicado a generar una respuesta cuenta contra la vida útil, por lo que el margen para que una solicitud posterior reutilice la caché es la vida útil menos el tiempo de generación.
Si tus solicitudes producen respuestas largas y la siguiente solicitud podría no comenzar hasta después de que transcurra la vida útil, usa el [TTL de caché de 1 hora](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#1-hour-cache-duration).
Puedes definir hasta 4 puntos de interrupción de caché (usando parámetros `cache_control`) en tu prompt.
El almacenamiento en caché de prompts es compatible con todos los [modelos de Claude activos](https://platform.claude.com/docs/es/models/overview).
Cambiar los parámetros de pensamiento (cambiar de modo o cambiar el presupuesto en el modo extendido) invalida los prefijos de mensajes almacenados en caché y también puede invalidar las indicaciones del sistema y las herramientas almacenadas en caché, porque la configuración de pensamiento se renderiza en el prompt. El valor de [`output_config.effort`](https://platform.claude.com/docs/es/build-with-claude/effort) se comporta de la misma manera.
Para obtener más detalles sobre la invalidación de la caché, consulta [Qué invalida la caché](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#what-invalidates-the-cache).
Para obtener más información sobre el pensamiento, incluida su interacción con el uso de herramientas y el almacenamiento en caché de prompts, consulta [Pensamiento y almacenamiento en caché de prompts](https://platform.claude.com/docs/es/build-with-claude/thinking#thinking-and-prompt-caching).
La forma más sencilla es agregar `"cache_control": {"type": "ephemeral"}` en el nivel superior del cuerpo de tu solicitud ([almacenamiento en caché automático](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#automatic-caching)). Como alternativa, incluye al menos un punto de interrupción `cache_control` en bloques de contenido individuales ([puntos de interrupción de caché explícitos](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#explicit-cache-breakpoints)).
Sí, el almacenamiento en caché de prompts se puede usar junto con otras funciones de la API, como el uso de herramientas y las capacidades de visión. Sin embargo, cambiar si hay imágenes en un prompt o modificar la configuración del uso de herramientas romperá la caché.
Para obtener más detalles sobre la invalidación de la caché, consulta [Qué invalida la caché](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#what-invalidates-the-cache).
El almacenamiento en caché de prompts introduce una nueva estructura de precios en la que las escrituras en caché de 5 minutos cuestan un 25 % más que los tokens de entrada base, las escrituras en caché de 1 hora cuestan 2 veces los tokens de entrada base y los aciertos de caché cuestan una fracción del precio base de los tokens de entrada (consulta [Precios](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#pricing) para ver el multiplicador por modelo).
Actualmente, no hay forma de borrar la caché manualmente. Los prefijos almacenados en caché expiran automáticamente tras un mínimo de 5 minutos de inactividad.
Puedes supervisar el rendimiento de la caché usando los campos `cache_creation_input_tokens` y `cache_read_input_tokens` en la respuesta de la API.
Consulta [Qué invalida la caché](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#what-invalidates-the-cache) para obtener más detalles sobre la invalidación de la caché, incluida una lista de cambios que requieren crear una nueva entrada de caché.
El almacenamiento en caché de prompts está diseñado con sólidas medidas de privacidad y separación de datos:
1. Las claves de caché se generan usando un hash criptográfico de los prompts hasta el punto de control de caché. Esto significa que solo las solicitudes con prompts idénticos pueden acceder a una caché específica.
2. En la Claude API, Claude Platform on AWS y Microsoft Foundry, las cachés están aisladas por espacio de trabajo dentro de una organización. En Bedrock y Google Cloud, las cachés están aisladas por organización. En todos los casos, las cachés nunca se comparten entre organizaciones, ni siquiera para prompts idénticos. Consulta [Almacenamiento y uso compartido de la caché](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#cache-storage-and-sharing) para obtener más detalles.
3. El mecanismo de almacenamiento en caché está diseñado para mantener la integridad y la privacidad de cada conversación o contexto único.
4. Es seguro usar `cache_control` en cualquier parte de tus prompts. Para que el almacenamiento en caché produzca lecturas, coloca el punto de interrupción al final de un prefijo estable: colocarlo en un bloque que cambia en cada solicitud (como una marca de tiempo o la entrada arbitraria del usuario) escribe una entrada nueva cada vez y nunca produce aciertos.
Estas medidas garantizan que el almacenamiento en caché de prompts mantenga la privacidad y la seguridad de los datos, a la vez que ofrece beneficios de rendimiento.
Sí, es posible usar el almacenamiento en caché de prompts con tus solicitudes de la [Batches API](https://platform.claude.com/docs/es/build-with-claude/batch-processing). Sin embargo, como las solicitudes por lotes asíncronas pueden procesarse de forma concurrente y en cualquier orden, los aciertos de caché se proporcionan en la medida de lo posible.
La [caché de 1 hora](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#1-hour-cache-duration) puede ayudar a mejorar tus aciertos de caché. La forma más rentable de usarla es la siguiente:
* Reúne un conjunto de solicitudes de mensajes que tengan un prefijo compartido.
* Envía una solicitud por lotes con una sola solicitud que tenga este prefijo compartido y un bloque de caché de 1 hora. Esto escribe el prefijo en la caché de 1 hora.
* En cuanto esto termine, envía el resto de las solicitudes. Tendrás que supervisar el trabajo para saber cuándo termina.
Esto suele ser mejor que usar la caché de 5 minutos, porque es común que las solicitudes por lotes tarden entre 5 minutos y 1 hora en completarse.
Este error suele aparecer cuando actualizaste tu SDK o estás usando ejemplos de código desactualizados. El almacenamiento en caché de prompts ya no requiere el prefijo beta. En lugar de:
```python Python
client.beta.prompt_caching.messages.create(**params)
```
Usa:
```python Python
client.messages.create(**params)
```
Este error suele aparecer cuando actualizaste tu SDK o estás usando ejemplos de código desactualizados. El almacenamiento en caché de prompts ya no requiere el prefijo beta. En lugar de:
```typescript TypeScript
client.beta.promptCaching.messages.create(/* ... */);
```
Usa:
```typescript
client.messages.create(/* ... */);
```