---
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.
featureMetadata:
zdr:
eligibility: eligible
note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements). Tus prompts y las salidas de Claude no se almacenan. Las representaciones de la caché KV y los hashes criptográficos se mantienen en memoria durante el TTL de la caché y se eliminan sin demora tras su vencimiento.
supportedModels:
- claude-fable-5-2
- claude-mythos-5-2
- claude-fable-5-1
- claude-mythos-5-1
- claude-fable-5
- claude-mythos-5
- claude-mythos-preview
- claude-opus-5-5
- claude-opus-5
- claude-sonnet-5-5
- claude-sonnet-5
- claude-haiku-5-5
- claude-haiku-4-5-20251001
- claude-opus-4-8
- claude-opus-4-7
- claude-opus-4-6
- claude-sonnet-4-6
- claude-opus-4-5-20251101
- claude-sonnet-4-5-20250929
supportedPlatforms:
Claude API: stable
Amazon Bedrock: stable
Amazon Bedrock (bedrock-runtime): stable
Claude Platform on AWS: stable
Claude Models on Google Cloud (Anthropic managed): stable
Claude Models on Google Cloud (Google managed): stable
Microsoft Foundry: stable
---
**Compatibilidad con la API**: El uso varía según el producto.
* **Messages API**: Actívalo con `cache_control`, en el nivel superior o en bloques.
* **Managed Agents**: Siempre activo. Las entradas de caché usan una duración de 5 minutos de forma predeterminada, y las lecturas y escrituras de caché aparecen en el uso de la sesión.
El “prompt caching” (almacenamiento en caché de prompts) optimiza tu uso de la API al permitir que la API reanude 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.
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 punto de interrupción de caché al último bloque almacenable en caché y lo mueve hacia adelante a medida que crecen las conversaciones. Ideal para conversaciones de múltiples turnos donde 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 un control detallado sobre exactamente qué se almacena en caché.
Una forma de comenzar 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: 2026-10-21" \
-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 <<'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 UserMessageParam { 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;
// ...
void main() {
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);
IO.println(message.usage());
}
```
```php PHP
use Anthropic\Messages\CacheControlEphemeral;
use Anthropic\Messages\Model;
// ...
$client = new Client();
$response = $client->messages->create(
maxTokens: 1024,
messages: [
['role' => 'user', 'content' => "Analyze the major themes in 'Pride and Prejudice'."]
],
model: 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: Anthropic::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é 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 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 posterior que reutilice el mismo prefijo en caché debe comenzar aproximadamente dentro de 1 minuto después de que termine esa respuesta.
Si 5 minutos es muy poco tiempo, puedes usar una [duración de caché de 1 hora](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#1-hour-cache-duration) con un costo adicional (consulta [Precios](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#pricing)).
El almacenamiento en caché de prompts abarca el prefijo completo: `tools`, `system` y `messages` (en ese orden), hasta el bloque designado con `cache_control`, inclusive.
***
## Precios
El almacenamiento en caché de prompts tiene sus propios 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.2 | $8 / MTok | $10 / MTok | $16 / MTok | $0.20 / MTok1 | $40 / MTok |
| Claude Mythos 5.2 ([limited availability](https://support.claude.com/en/articles/14604842)) | $8 / MTok | $10 / MTok | $16 / MTok | $0.20 / MTok1 | $40 / MTok |
| 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 Claude Models on Google Cloud (Google managed) and Bedrock](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 Claude Models on Google Cloud (Google managed)](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 Claude Models on Google Cloud (Google managed) and Bedrock](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 |
*1 Cache hits and refreshes on Claude Fable 5.2, Claude Mythos 5.2, 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é con un TTL de 5 minutos cuestan 1.25 veces el precio base de los tokens de entrada.
* Los tokens de escritura en caché con un TTL 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 API de Batch, 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 Claude activos](https://platform.claude.com/docs/es/models/overview).
***
## Almacenamiento en caché automático
El almacenamiento en caché automático habilita el almacenamiento en caché de prompts con un solo campo. 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: 2026-10-21" \
-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 <<'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 UserMessageParam { Content = "My name is Alex. I work on machine learning." },
new AssistantMessageParam
{
Content = "Nice to meet you, Alex! How can I help with your ML work today?"
},
new UserMessageParam { 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;
// ...
void main() {
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);
IO.println(message.usage());
}
```
```php PHP
use Anthropic\Messages\CacheControlEphemeral;
use Anthropic\Messages\Model;
// ...
$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: 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: Anthropic::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é se mueve hacia adelante 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 caché |
| ----------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| Solicitud 1 | System
+ User(1) + Asst(1)
+ **User(2)** ◀ caché | Todo se escribe en caché |
| Solicitud 2 | System
+ User(1) + Asst(1)
+ User(2) + Asst(2)
+ **User(3)** ◀ caché | Desde System hasta User(2) se lee desde caché;
Asst(2) + User(3) se escriben en 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 caché;
Asst(3) + User(4) se escriben en 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 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 usa una de las 4 ranuras 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 gestiona 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?" }]
}
```
### Qué permanece 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 búsqueda retroactiva de 20 bloques se aplican igual 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 ranuras 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 [Amazon Bedrock (`bedrock-runtime`)](https://platform.claude.com/docs/es/build-with-claude/claude-on-amazon-bedrock-legacy). Allí, 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 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 el almacenamiento 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 encuentra automáticamente el prefijo más largo que una solicitud anterior ya escribió 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, verificando 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 ventana de búsqueda retroactiva es de 20 bloques.** El sistema verifica como máximo 20 posiciones por cada 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 API de Claude, 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 paralelas a herramientas no empuja por sí solo la entrada de la solicitud anterior fuera de la ventana.
**Ejemplo: búsqueda retroactiva en una conversación creciente**
Agregas bloques nuevos 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, así que no hay acierto de caché. Agregar un segundo punto de interrupción en el bloque 15 inicia allí una segunda ventana de búsqueda retroactiva, 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, así que el hash del prefijo en el bloque 6 es diferente. La búsqueda retroactiva 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 una nueva escritura en caché en cada solicitud y nunca obtienes una lectura.
La búsqueda retroactiva 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 permanece 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) tiene el mismo problema: 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 todas 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, así que la búsqueda retroactiva 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 diariamente)
* Tener más control sobre exactamente qué se almacena en caché
* Asegurar 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 búsqueda retroactiva 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 búsqueda retroactiva 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.
### Comprender los costos de los puntos de interrupción de caché
**Los puntos de interrupción de caché en sí mismos no agregan ningún costo.** Solo se te cobra por:
* **Escrituras en caché:** Cuando se escribe contenido nuevo en la caché (25 por ciento más que los tokens de entrada base para un TTL de 5 minutos)
* **Lecturas de caché:** Cuando se usa contenido en caché (10 por ciento del precio base de los tokens de entrada, con [excepciones por modelo](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#pricing))
* **Tokens de entrada normales:** Por cualquier contenido no almacenado 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 pueden almacenarse en caché de forma independiente.
***
## Estrategias y consideraciones de almacenamiento en caché
### Limitaciones de la caché
En la API de Claude, [Claude Platform on AWS](https://platform.claude.com/docs/es/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/es/build-with-claude/claude-models-on-google-cloud/google-managed) 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.2, [Claude Mythos 5.2](https://platform.claude.com/docs/es/models/mythos-5-2/overview), 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 Claude Models on Google Cloud (Google managed) y Bedrock](https://platform.claude.com/docs/es/about-claude/model-deprecations)), Claude Opus 4 ([retirado, excepto en Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/es/about-claude/model-deprecations)) y Claude Sonnet 4 ([retirado, excepto en Claude Models on Google Cloud (Google managed) y Bedrock](https://platform.claude.com/docs/es/about-claude/model-deprecations))
* 4,096 tokens para Claude Haiku 4.5
Estos mínimos se aplican en cada una de estas plataformas donde el 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 procesa 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é, así que alcanzar el mínimo puede reducir los costos de los prompts que se reutilizan con frecuencia.
[Amazon Bedrock (`bedrock-mantle`)](https://platform.claude.com/docs/es/build-with-claude/claude-in-amazon-bedrock) es una plataforma operada por AWS. En Amazon 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 en caso de fallo 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 paralelas, espera la primera respuesta antes de enviar las solicitudes posteriores.
`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)) en sí mismos 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 manera eficaz, almacenando en caché los documentos a los que hacen 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 distintos 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 (modo y `budget_tokens` en 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) puede invalidar los bloques de mensajes y, en algunos modelos, también las cachés de herramientas y del sistema (consulta [Pensamiento y almacenamiento en caché de prompts](https://platform.claude.com/docs/es/build-with-claude/thinking#thinking-and-prompt-caching)). Establecer explícitamente el esfuerzo 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-per-message), 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 enviados a solicitudes con pensamiento** | ✓ | ✓ | Específico del modelo | En Claude Opus 4.5 y modelos Opus posteriores, Claude Sonnet 4.6 y modelos Sonnet posteriores, Claude Haiku 5.5 y todos los modelos Claude Fable y Claude Mythos, los bloques de pensamiento se conservan de forma predeterminada, por lo que la caché sigue siendo válida (✓). En otros modelos, 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 omitidos** | ✓ | ✓ | ✘ | Cuando la API omite un bloque de pensamiento que no está [preservado](https://platform.claude.com/docs/es/build-with-claude/thinking#preserved-thinking) en esa solicitud, 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, así que solo el mensaje agregado se procesa como entrada nueva. La única excepción es un arreglo `tools` sin ninguna herramienta no diferida, donde 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.2, [Claude Mythos 5.2](https://platform.claude.com/docs/es/models/mythos-5-2/overview), 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 5, Claude Opus 4.8, 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é permanezca 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 y cambios de herramientas 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 la caché ni se usaron para crearla (es decir, los tokens después del último punto de interrupción de caché)
**Comprender 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 comprender tanto los costos como los “rate limits” (límites de velocidad), ya que `input_tokens` normalmente es 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 ocurre comúnmente 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 caché:**
* La caché sigue siendo válida cuando solo se proporcionan resultados de herramientas como mensajes del usuario.
* En Claude Opus 4.5 y modelos Opus posteriores, Claude Sonnet 4.6 y modelos Sonnet posteriores, Claude Haiku 5.5 y todos los modelos Claude Fable y Claude Mythos, los bloques de pensamiento se conservan de forma predeterminada incluso cuando se agrega contenido de usuario que no es un resultado de herramienta, por lo que la caché sigue siendo válida.
* En otros modelos, agregar contenido de usuario que no es un resultado de herramienta invalida la caché y elimina del contexto todos los bloques de pensamiento anteriores.
* 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 que conservan el pensamiento anterior](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#caching-with-thinking-blocks), los bloques de pensamiento anteriores permanecen en el contexto de forma predeterminada y siguen formando parte del prefijo en caché. En otros modelos, todos los bloques de pensamiento anteriores se eliminan del contexto en este punto.
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 API de Claude, Claude Platform on AWS y Microsoft Foundry; Claude Models on Google Cloud (Google managed) y Bedrock 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 diferentes 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 API de Claude, Claude Platform on AWS y Microsoft Foundry; Claude Models on Google Cloud (Google managed) y Bedrock usan solo aislamiento a nivel de organización.
* **Coincidencia exacta:** Los aciertos de caché requieren segmentos de prompt 100 por ciento idénticos, incluidos todos los textos e 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:
* Comienza 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 automáticamente los puntos de interrupción.
* 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é estratégicamente para separar diferentes secciones de prefijos almacenables en caché.
* Coloca el punto de interrupción en el último bloque que permanece 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 regularmente las tasas de acierto 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 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 en tu prompt material extenso completo, incluidas imágenes, 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.
* Libros, artículos, documentación, transcripciones de podcasts y otro contenido extenso: haz que cualquier base de conocimiento sea interactiva incrustando 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 permanece 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 búsqueda retroactiva 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 invalidan la caché, lo que requiere 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 (consulta [Precios](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#pricing)).
La duración de caché de 1 hora está disponible en la API de Claude, [Amazon Bedrock (`bedrock-mantle`)](https://platform.claude.com/docs/es/build-with-claude/claude-in-amazon-bedrock), [Amazon Bedrock (`bedrock-runtime`)](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), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/es/build-with-claude/claude-models-on-google-cloud/google-managed) 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
}
}
}
```
El campo `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 [Los resultados de las herramientas de servidor se almacenan en caché automáticamente](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 usas un prompt con una cadencia regular (por ejemplo, una indicación del sistema que envías con más frecuencia que cada 5 minutos), sigue usando la caché de 5 minutos, ya que esta sigue actualizándose sin cargo adicional.
La caché de 1 hora es más útil en los siguientes escenarios:
* Cuando tienes prompts que probablemente se usan con menos frecuencia que cada 5 minutos, pero con más frecuencia que cada hora. Por ejemplo, cuando un agente secundario agéntico tarda más de 5 minutos, o cuando almacenas una conversación de chat larga con un usuario y generalmente esperas que ese usuario quizá no responda en los próximos 5 minutos.
* Cuando la latencia es importante y tus prompts de seguimiento podrían 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.
Las cachés de 5 minutos y de 1 hora se comportan igual en cuanto a la latencia. Generalmente verás una mejora en el “time-to-first-token” (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 de Claude determina tres ubicaciones de facturación en tu prompt:
1. Posición `A`: el recuento de tokens en el último acierto de caché en tu prompt (o 0 si no hay aciertos).
* Un acierto en una entrada de caché con un TTL de 5 minutos no cuenta como acierto si un bloque `cache_control` con un TTL de 1 hora, ubicado más adelante que esa entrada en el prompt, es un fallo de caché.
* Una solicitud que lee una entrada de caché con un TTL de 5 minutos reinicia la vida útil de 5 minutos de esa entrada, aunque esta vez la solicitud establezca `"ttl": "1h"`.
2. Posición `B`: el recuento de tokens en el último bloque `cache_control` de 1 hora ubicado más adelante que `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é.
Se te cobra 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 solicitudes de ejemplo, cada una con diferentes aciertos y fallos de caché. Cada una tiene un precio calculado diferente, que se muestra en los recuadros.
***
## Precalentar la caché
El “cache pre-warming” (precalentamiento de la 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 puede reducir la penalización de latencia por fallo de caché en la primera interacción del usuario, disminuyendo el “time-to-first-token” (tiempo hasta el primer token), o TTFT, para 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 punto de interrupción `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 de seguimiento (normalmente tu indicación del sistema o tus definiciones de herramientas), no en el mensaje de usuario de marcador de posición. De lo contrario, la entrada de caché queda asociada al marcador de posición y la solicitud de seguimiento no la aprovechará. Usa también la misma configuración de pensamiento y el mismo `output_config.effort` que en tus solicitudes de seguimiento: 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 aproveche. Esto significa 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), porque el almacenamiento en caché automático coloca el punto de interrupción en el último bloque, que aquí es el marcador de posición. El mensaje de usuario de marcador de posición 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. Se facturan cero tokens 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: 2026-10-21" \
-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 <<'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 UserMessageParam { 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
Realiza una solicitud de precalentamiento cuando tu aplicación se inicie (o en un intervalo programado) y luego envía las solicitudes reales de los usuarios después de que se complete el precalentamiento:
```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: 2026-10-21" \
-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: 2026-10-21" \
-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 <<'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 <<'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 cualquier 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 cualquier 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.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 UserMessageParam { 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 UserMessageParam { Content = userMessage }],
}
);
// Precalienta la caché antes de que llegue cualquier 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é.
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 cualquier 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 cualquier 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 cualquier 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 instanceof \Anthropic\Messages\TextBlock) {
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)
# Más tarde, 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.is_a?(Anthropic::Models::TextBlock)
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, porque 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 apunta 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 de seguimiento.
### Reemplazar la solución alternativa de `max_tokens=1`
Algunas aplicaciones envían solicitudes con `max_tokens: 1` para calentar la caché. Prefiere `max_tokens: 0` cuando la solicitud lo permita: no se produce ninguna salida, por lo que no hay una respuesta de un solo token que descartar, no se facturan tokens 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), la [receta de almacenamiento en caché de prompts](https://platform.claude.com/cookbook/misc-prompt-caching) en el Claude Cookbook ofrece ejemplos detallados y mejores 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: 2026-10-21" \
-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 <<'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 UserMessageParam
{
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;
// ...
void main() {
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);
IO.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: 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: Anthropic::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 se mantiene la instrucción del usuario 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 hay nueva creación de 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 su lugar 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: 2026-10-21" \
-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 <<'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 UserMessageParam
{
Content = new List
{
new ContentBlockParam(new TextBlockParam("Hello, can you tell me more about the solar system?")),
},
},
new AssistantMessageParam
{
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 UserMessageParam
{
Content = 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?")),
anthropic.NewUserMessage(
anthropic.NewTextBlock("Good to know."),
anthropic.ContentBlockParamUnion{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;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Crear indicación del sistema efímera
TextBlockParam systemPrompt = TextBlockParam.builder()
.text("...long system prompt")
.cacheControl(CacheControlEphemeral.builder().build())
.build();
// Crear 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é)
.addUserMessageOfContentBlockParams(
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);
IO.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: 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: Anthropic::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 más larga de bloques previamente almacenada en caché para los mensajes de seguimiento. Los bloques que se marcaron con `cache_control` en un turno anterior no se vuelven a marcar, pero una solicitud dentro de 5 minutos aún los lee desde la caché y renueva su vida útil.
El parámetro `cache_control` también está en el mensaje del sistema. Si el mensaje del sistema se expulsa de la caché tras más de 5 minutos sin usarse, la siguiente solicitud lo vuelve a agregar.
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 (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: 2026-10-21" \
-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 <<'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.
# 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"},
}
],
},
],
)
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.
# 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" }
}
]
}
]
});
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.
# 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
""",
CacheControl = new CacheControlEphemeral(),
},
new TextBlockParam()
{
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...]
""",
CacheControl = new CacheControlEphemeral(),
},
}),
Messages =
[
new UserMessageParam { Content = "Can you search for information about Mars rovers?" },
new AssistantMessageParam
{
Content = new List
{
new ContentBlockParam(new ToolUseBlockParam()
{
ID = "tool_1",
Name = "search_documents",
Input = new Dictionary
{
["query"] = JsonSerializer.SerializeToElement("Mars rovers"),
},
}),
},
},
new UserMessageParam
{
Content = 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 AssistantMessageParam
{
Content = "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.",
},
new UserMessageParam
{
Content = 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.
# 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`,
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
{
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...]`,
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.")),
anthropic.NewUserMessage(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;
// ...
void main() {
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.
# 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"""
)
.cacheControl(CacheControlEphemeral.builder().build())
.build(),
TextBlockParam.builder()
.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...]"""
)
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
)
// Historial de la conversación
.addUserMessage("Can you search for information about Mars rovers?")
.addAssistantMessageOfContentBlockParams(
List.of(
ContentBlockParam.ofToolUse(
ToolUseBlockParam.builder()
.id("tool_1")
.name("search_documents")
.input(JsonValue.from(Map.of("query", "Mars rovers")))
.build()
)
)
)
.addUserMessageOfContentBlockParams(
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()
)
)
)
.addAssistantMessageOfContentBlockParams(
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()
)
)
)
.addUserMessageOfContentBlockParams(
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);
IO.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: Model::CLAUDE_OPUS_5_5,
system: [
[
'type' => 'text',
'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
TEXT,
'cache_control' => ['type' => 'ephemeral']
],
[
'type' => 'text',
'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...]
TEXT,
'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: Anthropic::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: <<~TEXT.chomp,
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
TEXT
cache_control: { type: "ephemeral" }
},
{
type: "text",
text: <<~TEXT.chomp,
# 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...]
TEXT
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 conocimientos 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 ZDR. Anthropic no almacena el texto sin procesar de tus prompts ni de las respuestas de Claude.
Las representaciones de la caché KV (“key-value”, 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 API de Claude, Claude Platform on AWS y Microsoft Foundry, entre espacios de trabajo dentro de una organización.
***
## Preguntas frecuentes
**En la mayoría de los casos, un único punto de interrupción de caché al final de tu contenido estático es suficiente.** Las escrituras en caché ocurren solo en el bloque que marcas. Colócalo en el último bloque que permanece idéntico entre solicitudes, y cada solicitud posterior leerá esa misma entrada. Si un bloque posterior varía con 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 en crecimiento 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 hacia atrás
* Quieres almacenar en caché de forma independiente secciones que se actualizan con distintas frecuencias
* Necesitas control explícito sobre qué se almacena en caché para optimizar costos
Ejemplo: si tienes instrucciones del sistema (rara vez cambian) y contexto RAG (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 por ciento 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](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 se almacenó 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 es 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 la ventana para que una solicitud de seguimiento 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. Cambiar el valor de [`output_config.effort`](https://platform.claude.com/docs/es/build-with-claude/effort) puede tener el mismo efecto.
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 rompe 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 tiene sus propios precios: las escrituras en caché de 5 minutos cuestan un 25 por ciento 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](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#pricing), con un multiplicador para cada modelo.
No hay forma de borrar la caché manualmente. Los prefijos almacenados en caché expiran automáticamente después de 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 API de Claude, Claude Platform on AWS y Microsoft Foundry, las cachés están aisladas por espacio de trabajo dentro de una organización. En Claude Models on Google Cloud (Google managed) y Bedrock, 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 obtiene un acierto.
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í, puedes usar el almacenamiento en caché de prompts con tus solicitudes de la [Message 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 simultánea 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 compartan un prefijo.
* 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 se complete, envía el resto de las solicitudes. Tienes que supervisar el trabajo para saber cuándo se completa.
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 está disponible en `client.messages`, sin 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 está disponible en `client.messages`, sin el prefijo beta. En lugar de:
```typescript TypeScript
client.beta.promptCaching.messages.create(/* ... */);
```
Usa:
```typescript
client.messages.create(/* ... */);
```
## Disponibilidad
Almacenamiento en caché de prompts está disponible o en beta, según la API, y es elegible para retención de datos cero y preparación para HIPAA.
### Compatibilidad con la API
#### [Messages API](https://platform.claude.com/docs/es/build-with-claude/working-with-messages)
* Disponibilidad: Disponible
* Uso: Actívalo con `cache_control`, en el nivel superior o en bloques.
| Estado | Plataformas en la nube | Modelos |
| ---------- | --------------------------------- | ------------------------------------------------------------------------ |
| Disponible | Todas las plataformas compatibles | [Todos los modelos](https://platform.claude.com/docs/es/models/overview) |
#### [Managed Agents](https://platform.claude.com/docs/es/managed-agents/overview)
* Disponibilidad: Siempre activo
* Uso: Las entradas de caché usan una duración de 5 minutos de forma predeterminada, y las lecturas y escrituras de caché aparecen en el uso de la sesión.
| Estado | Plataformas en la nube | Modelos |
| ------ | --------------------------------- | ------------------------------------------------------------------------ |
| Beta | Todas las plataformas compatibles | [Todos los modelos](https://platform.claude.com/docs/es/models/overview) |
### Manejo de datos
[Descripción general del manejo de datos](https://platform.claude.com/docs/es/manage-claude/api-and-data-retention#feature-eligibility)
| Elemento | Retención de datos cero | HIPAA |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| Estado | Elegible (excluye [Modelos cubiertos](https://platform.claude.com/docs/es/manage-claude/api-and-data-retention#model-specific-data-retention-requirements)) | Elegible |
| Detalles | Tus prompts y las salidas de Claude no se almacenan. Las representaciones de la caché KV y los hashes criptográficos se mantienen en memoria durante el TTL de la caché y se eliminan sin demora tras su vencimiento. [Más información](https://platform.claude.com/docs/es/build-with-claude/prompt-caching#data-retention) | — |
Endpoints aplicables:
* `/v1/messages`