---
title: "Uso y facturación de Prompt Caching"
description: "Uso de Claude Prompt Caching en 1折AI: cómo activarlo, longitud mínima, cómo confirmar un acierto, cómo se facturan los aciertos y el comportamiento de almacenamiento en caché de Claude Code."
headingIds: {"Resumen primero":"section-1","Cómo activarlo":"section-2","Longitud mínima para almacenar en caché":"section-3","Confirmar un acierto":"section-4","Cómo se factura":"section-5","Caché de 1 hora":"section-6","Almacenamiento en caché de Claude Code":"section-7","¿Puede la interfaz compatible con OpenAI usar almacenamiento en caché?":"section-8","Preguntas frecuentes":"section-9"}
---
Prompt Caching permite que el prefijo largo que envías repetidamente (prompt del sistema, definiciones de herramientas, documentos largos, historial de conversación) se facture como escritura solo la primera vez, y como lectura a partir de entonces. En este sitio, las lecturas y escrituras de caché se facturan a los precios de lista oficiales, sin aplicar el descuento de entrada/salida. Los precios unitarios de caché por modelo se enumeran en [Modelos y precios](https://1zheai.com/en/pricing/).
## Resumen primero
- **Claude Code tiene el almacenamiento en caché activado de forma predeterminada**; entra en vigor en cuanto te conectas.
- Al llamar desde tu propio código, añade `cache_control` al bloque de contenido que deseas almacenar en caché, usando el nativo `/v1/messages`. La interfaz compatible con OpenAI actualmente no almacena en caché.
- Para determinar si hubo un acierto, comprueba únicamente si el `usage.cache_read_input_tokens` de la respuesta es mayor que 0.
- La caché vive 5 minutos de forma predeterminada, y cada acierto reinicia el temporizador. También puedes usar `"ttl": "1h"` para escribir una caché de 1 hora, a un precio de escritura más alto.
## Cómo activarlo
Añade `"cache_control": {"type": "ephemeral"}` a un bloque de contenido en system, tools o messages; ese bloque y todo lo anterior se almacenará en caché. Una sola solicitud puede tener como máximo 4 puntos de interrupción de caché.
```bash
curl https://1zheai.com/v1/messages \
-H "x-api-key: $ONEZHE_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 256,
"system": [
{
"type": "text",
"text": "这里放一段很长、每次都一样的内容：项目说明、代码规范、参考文档……",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [{"role": "user", "content": "根据上面的规范，审查这段代码：..."}]
}'
```
Si el prefijo a almacenar en caché es demasiado corto, la solicitud se procesa normalmente pero simplemente no se almacena en caché, y no se genera ningún error. La longitud mínima varía según el modelo; consulta la tabla a continuación.
## Longitud mínima para almacenar en caché
Lo siguiente proviene de [la documentación oficial de Anthropic](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) (2026-10-14):
| Recuento mínimo de tokens | Modelos |
|---|---|
| 512 | Fable 5.1, Fable 5, Opus 5.5, Opus 5, Sonnet 5.5, Haiku 5.5 |
| 1,024 | Opus 4.8, Sonnet 5, Sonnet 4.6, Sonnet 4.5 |
| 2,048 | Opus 4.7 |
| 4,096 | Opus 4.6, Opus 4.5, Haiku 4.5 |
## Confirmar un acierto
Envía la misma solicitud dos veces (con no más de 5 minutos de diferencia) y compara el `usage` de ambas. A continuación se muestran resultados reales medidos el 2026-10-15 con `claude-sonnet-5-5`, con aproximadamente 18,000 tokens de texto fijo en el sistema:
```json title="第一次：写入缓存"
{
"input_tokens": 23,
"cache_creation_input_tokens": 17920,
"cache_read_input_tokens": 0,
"cache_creation": {"ephemeral_5m_input_tokens": 17920, "ephemeral_1h_input_tokens": 0},
"output_tokens": 4
}
```
```json title="第二次：命中缓存"
{
"input_tokens": 23,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 17920,
"cache_creation": {"ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 0},
"output_tokens": 4
}
```
Si el segundo `cache_read_input_tokens` es mayor que 0, se está leyendo la caché. Los tokens de escritura y lectura de caché de cada llamada también aparecen en la columna Token del [registro de llamadas](/es/docs/usage-logs/), con las lecturas registradas como "cache↓" y las escrituras como "↑".
## Cómo se factura
| Tipo | Precio unitario oficial | Precio unitario de 1折AI |
|---|---|---|
| Escritura de caché (5 minutos) | Precio de entrada × 1.25 | Precio de lista oficial, sin descuento |
| Escritura de caché (1 hora) | Precio de entrada × 2 | Precio de lista oficial, sin descuento |
| Lectura de caché | Precio de entrada × 0.1 (0.05 para Opus 5.5 y Sonnet 5.5, 0.025 para Fable 5.1) | Precio de lista oficial, sin descuento |
El precio oficial de una escritura de caché de 5 minutos es típicamente 1.25 veces el precio oficial de entrada. En este sitio, la entrada tiene un descuento pero el almacenamiento en caché no, por lo que no puedes usar el multiplicador oficial para concluir que una sola lectura de caché se paga por sí misma; necesitas comparar el descuento del modelo, el costo de escritura y el número de lecturas repetidas. Ejemplos completos resueltos están en [Precios y facturación](/es/docs/pricing-explained/).
### Caché de 1 hora
Añade `"ttl": "1h"` a `cache_control`, y la caché se conservará durante 1 hora — adecuada para prefijos con intervalos superiores a 5 minutos que aún se usan repetidamente:
```json
"cache_control": {"type": "ephemeral", "ttl": "1h"}
```
Las escrituras se facturan a 2 veces el precio oficial de entrada, no al precio de entrada con descuento; las lecturas son las mismas que la caché de 5 minutos. Los tokens escritos aparecen en `cache_creation.ephemeral_1h_input_tokens` de la respuesta. Si elegir la caché de 1 hora debe juzgarse en función del intervalo entre las dos solicitudes, el costo de escritura y el número de lecturas repetidas.
## Almacenamiento en caché de Claude Code
Claude Code coloca automáticamente puntos de interrupción de caché en el prompt del sistema, las definiciones de herramientas y el historial de conversación; [la explicación oficial está aquí](https://code.claude.com/docs/zh-CN/prompt-caching). Para que acierte mejor:
- Trabaja continuamente dentro de una sesión; no te detengas mucho tiempo en el medio. La caché expira si no se usa durante 5 minutos.
- Las solicitudes posteriores en la misma sesión leerán la caché. Medido el 2026-10-15, para una tarea de Claude Code de dos rondas, la segunda ronda leyó 31,440 tokens de caché y escribió 115 tokens. Al iniciar una nueva sesión, la primera ronda puede necesitar reescribir todo el prefijo (medido en aproximadamente 30,000 tokens), y esa llamada será más cara que las posteriores.
- Evita cambiar `CLAUDE.md`, cambiar de servidores MCP o cambiar de modelos a mitad de sesión; todo esto cambia el prefijo.
- No establezcas `DISABLE_PROMPT_CACHING=1`; esta variable de entorno desactiva el almacenamiento en caché para todos los modelos.
## ¿Puede la interfaz compatible con OpenAI usar almacenamiento en caché?
Actualmente, no. Medido el 2026-10-15, con aproximadamente 3,100 tokens de texto fijo en el mensaje del sistema de `/v1/chat/completions`, enviados dos veces seguidas, ya se añadiera o no `cache_control` al bloque de contenido, el `usage` de ambas respuestas fue:
```json
{"prompt_tokens": 3167, "completion_tokens": 4, "total_tokens": 3171}
```
No hay `prompt_tokens_details.cached_tokens`, y las lecturas y escrituras de caché en el registro de llamadas son ambas 0; toda la solicitud se factura al precio de entrada. Para escenarios que necesitan almacenamiento en caché, usa por favor `/v1/messages` (SDK de Anthropic o Claude Code).
## Preguntas frecuentes
La caché se escribió, pero la siguiente solicitud no la leyó. Depura en orden: ¿las dos solicitudes estuvieron separadas por más de 5 minutos? ¿El contenido antes del punto de interrupción era idéntico byte a byte (las marcas de tiempo y los IDs aleatorios en el sistema lo hacen diferente cada vez)? ¿Se cambió el modelo? ¿El prefijo alcanzó la longitud mínima anterior?
Los tokens de lectura y escritura de caché de cada llamada están en el registro de llamadas, así que puedes calcularlo tú mismo: lecturas de caché ÷ (entrada + escrituras de caché + lecturas de caché).