Uso y facturación de Prompt Caching

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.

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.

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

1
curl https://1zheai.com/v1/messages \
2
  -H "x-api-key: $ONEZHE_API_KEY" \
3
  -H "anthropic-version: 2023-06-01" \
4
  -H "content-type: application/json" \
5
  -d '{
6
    "model": "claude-sonnet-5-5",
7
    "max_tokens": 256,
8
    "system": [
9
      {
10
        "type": "text",
11
        "text": "这里放一段很长、每次都一样的内容：项目说明、代码规范、参考文档……",
12
        "cache_control": {"type": "ephemeral"}
13
      }
14
    ],
15
    "messages": [{"role": "user", "content": "根据上面的规范，审查这段代码：..."}]
16
  }'

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 (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:

第一次：写入缓存
第二次：命中缓存

{
  "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
}

{
  "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, 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.

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:

1
"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í. 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:

1
{"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

¿Por qué siempre solo hay cache_creation y no cache_read?

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?

¿Se puede ver la tasa de aciertos de caché?

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é).