Guía de costos de Prompt Caching: Cache Hits, prefijos y gasto real en la API

El costo del caché de prompts depende de si tu segunda solicitud es exactamente igual a la primera, no del descuento anunciado. En nuestra estimación para un prompt del sistema de 20,000 tokens en claude-sonnet-5, 1,000 solicitudes cuestan alrededor de $18.18 sin caché y alrededor de $2.00 cuando cada solicitud después de la primera acierta en el caché. El mismo prompt cuesta más que la línea base sin caché si el prefijo cambia en cada llamada. Esta guía utiliza los precios de TokenLab observados el 2026-10-03 para mostrar dónde se sitúa ese límite, y marca lo que no pudimos confirmar en la documentación.

Puntos clave

• En los cinco modelos que verificamos, una lectura de caché cuesta del 2% al 10% del precio de entrada normal. Dos de los cinco no listan precio de escritura en caché.
• Donde existe un precio de escritura, es igual a la entrada (deepseek-v4.1-flash) o 1.25 veces la entrada (claude-sonnet-5, claude-sonnet-5-5).
• Según nuestra aritmética, un acierto de caché por escritura compensa la prima de escritura de 1.25x. Eso asume que la entrada de caché sigue activa, y el tiempo de vida del caché no está documentado en la evidencia que leímos.
• El almacenamiento en caché solo reduce el lado de entrada de la factura. Los tokens de salida tienen el mismo precio que antes.
• La documentación de la API de TokenLab que leímos no menciona un campo de tokens en caché en usage. Registra el objeto sin procesar de tu propia prueba y reconcílialo con Usage.

Costo de caché de prompts por modelo: precios de lectura, escritura y entrada

Leímos la API del modelo en vivo para cada modelo a continuación el 2026-10-03. Los cinco listan prompt-cache en sus capacidades, y los precios se actualizaron por última vez el 2026-10-02T16:53:30.068Z. Los precios están en USD por cada 1M de tokens.

Modelo	Entrada	Lectura de caché	Escritura de caché	Lectura como parte de la entrada	Escritura vs entrada
claude-sonnet-5	0.90	0.09	1.125	10%	1.25x
claude-sonnet-5-5	0.60	0.06	0.75	10%	1.25x
gpt-5.5	1.50	0.15	ninguno listado	10%	no listado
deepseek-v4.1-flash (fuera de pico)	0.15	0.003	0.15	2%	1.0x
deepseek-v4.1-flash (pico)	0.30	0.006	0.30	2%	1.0x
gemini-3.8-flash	0.375	0.0375	ninguno listado	10%	no listado

Las dos columnas de porcentaje son nuestra propia división de los precios listados.

Fuentes, todas observadas el 2026-10-03:

• claude-sonnet-5 (página del modelo: /models/claude-5/claude-sonnet-5)
• claude-sonnet-5-5 (página del modelo: /models/claude-5/claude-sonnet-5-5)
• gpt-5.5 (página del modelo: /models/gpt-5-5/gpt-5.5)
• deepseek-v4.1-flash (página del modelo: /models/deepseek-v4/deepseek-v4.1-flash)
• gemini-3.8-flash (página del modelo: /models/gemini-3/gemini-3.8-flash)

Tres detalles importan al leer esta tabla.

Primero, gpt-5.5 y gemini-3.8-flash listan un precio de lectura de caché y ningún precio de escritura. No podemos decir a partir de estos datos cómo se factura un prefijo por primera vez en esos dos. La evidencia no dice que sea gratuito, y no dice que se facture a la tasa de entrada. Verifica Usage después de una primera solicitud antes de construir un pronóstico bajo cualquiera de las dos suposiciones.

Segundo, cuando leímos deepseek-v4.1-flash, encontramos dos entradas de precio. La entrada off-peak (selector offPeak: true) y la entrada peak (offPeak: false) difieren por un factor de dos en cada línea. Tus ahorros de caché por token son el mismo porcentaje, pero los dólares absolutos se duplican en pico.

Tercero, estos son precios públicos de TokenLab. La guía de facturación (observada el 2026-10-03) dice que una solicitud completada se cobra una vez por la opción de entrega que la produjo. Official sigue el precio público del fabricante del modelo, así que confirma qué opción sirvió tu solicitud antes de comparar con una hoja de precios del fabricante.

La referencia Get a Model muestra gpt-5.6-terra con prompt-cache entre sus capacidades. Su respuesta de ejemplo no contiene precios, por lo que dejamos ese modelo fuera de la tabla. No verificamos los otros modelos en el catálogo.

Un ejemplo práctico de costo de caché de prompts: un prompt del sistema largo

Aquí está el escenario, con cada entrada establecida para que puedas intercambiar tus propios números. Estas son nuestras suposiciones, no mediciones.

• Un prompt del sistema y bloque de herramientas de 20,000 tokens, idéntico en cada solicitud.
• Un mensaje de usuario de 200 tokens que cambia en cada solicitud.
• 1,000 solicitudes, con el caché manteniéndose vivo durante toda la ejecución, por lo que hay una escritura y 999 lecturas.
• Tokens de salida ignorados, porque cuestan lo mismo con o sin caché.

claude-sonnet-5 a 0.90 entrada, 0.09 lectura y 1.125 escritura por 1M de tokens:

• Sin caché: 1,000 × 20,200 = 20,200,000 tokens × $0.90/1M = $18.18
• Escritura en caché: 20,000 × $1.125/1M = $0.0225
• Lecturas de caché: 999 × 20,000 = 19,980,000 × $0.09/1M = $1.7982
• Sufijos sin caché: 1,000 × 200 = 200,000 × $0.90/1M = $0.18
• Con caché: 0.0225 + 1.7982 + 0.18 = alrededor de $2.00, aproximadamente 89% por debajo de la cifra sin caché

Ahora el caso de fallo, con el prefijo cambiando ligeramente en cada llamada para que cada solicitud pague una escritura y nunca lea. Eso cuesta 1,000 × 20,000 × $1.125/1M = $22.50 por prefijos, más los mismos $0.18 por sufijos. El total es alrededor de $22.68, que es $4.50 (25%) por encima de los $18.18 sin caché.

El punto de equilibrio se deriva de los mismos precios. Por cada 1M de tokens de prefijo, una escritura cuesta $0.225 más que la entrada simple, y cada lectura ahorra $0.81. Un acierto compensa la escritura con margen de sobra (0.225 ÷ 0.81 ≈ 0.28 lecturas por escritura).

El mismo escenario en los otros modelos:

Modelo	Sin caché	Con caché (estimado)	Suposición para la primera solicitud
claude-sonnet-5	$18.18	$2.00	precio de escritura listado
claude-sonnet-5-5	$12.12	$1.33	precio de escritura listado
deepseek-v4.1-flash fuera de pico	$3.03	$0.09	precio de escritura listado
deepseek-v4.1-flash pico	$6.06	$0.19	precio de escritura listado
gpt-5.5	$30.30	$3.33	no se lista precio de escritura; facturamos 20,000 tokens a la tasa de entrada
gemini-3.8-flash	$7.58	$0.83	no se lista precio de escritura; facturamos 20,000 tokens a la tasa de entrada

Para gpt-5.5, el cálculo es 20,000 × $1.50/1M = $0.03, más 19,980,000 × $0.15/1M = $2.997, más 200,000 × $1.50/1M = $0.30. Las dos filas marcadas se basan en una suposición que la evidencia no respalda, así que trátalas como aproximadas.

Hacer un prompt almacenable en caché: lo que confirma la documentación

La evidencia respalda una lista corta de requisitos.

1. Elige un modelo que liste prompt-cache. El array de capabilities de Get a Model (observado el 2026-10-03) es la verificación. Un modelo sin esto no te da base para esperar un descuento.
2. Mantén el contenido compartido en una posición estable. En el endpoint Messages, system es un campo de nivel superior y toma una cadena o un array de bloques de contenido. En Chat Completions, las instrucciones del sistema van en messages. De cualquier manera, el material repetido debe ir primero.
3. Envía bytes idénticos hasta el límite. Esta es la regla de prefijo exacto de la versión original de este artículo, y coincide con cómo funcionan los precios de la tabla. Un precio de lectura solo se aplica a la parte del prompt que coincidió.

Request A: [ System Prompt + Tool Definitions ] [ User Query A ]
           ▲───────────── CACHED PREFIX ────────▲ ▲── SUFFIX ──▲

Request B: [ System Prompt + Tool Definitions ] [ User Query B ]
           ▲─────────── CACHE HIT (READ) ───────▲ ▲── SUFFIX ──▲

Tres hábitos rompen la reutilización más a menudo:

• Marcas de tiempo, IDs de usuario o IDs de sesión en la parte superior de un prompt del sistema.
• Definiciones de herramientas o claves JSON reordenadas entre solicitudes.
• Cambios de sangría o nueva línea en el texto compartido.

Una forma de solicitud que documenta la referencia Create Message:

{
  "model": "claude-sonnet-5",
  "max_tokens": 512,
  "system": [
    {
      "type": "text",
      "text": "You are a support assistant. The following policy governs all responses: [Full Policy Text]"
    }
  ],
  "messages": [
    { "role": "user", "content": "What is the return period for damaged items?" }
  ]
}

Un borrador anterior de este artículo ponía un marcador cache_control de tipo ephemeral en ese bloque del sistema. La referencia Create Message que leímos el 2026-10-03 no lista ese campo, así que lo eliminamos de la muestra. Lo mismo ocurre con la longitud mínima del prefijo y el tiempo de vida del caché. No encontramos ninguna cifra para ninguno en la documentación de TokenLab que leímos. Antes de confiar en un marcador explícito o un TTL, prueba tu modelo elegido y compara los conteos de tokens en caché en dos llamadas idénticas.

Leer precios de caché y confirmar tokens en caché

No copies la tabla de arriba en el código. La guía de facturación dice que leas el precio actual cuando tu aplicación lo necesite. Dos rutas documentadas:

curl "https://api.tokenlab.sh/v1/models/claude-sonnet-5"
curl "https://api.tokenlab.sh/v1/pricing?provider=openai&tag=chat"

La primera devuelve las capacidades, límites y precios de un modelo. Un ID de modelo desconocido devuelve 404 model_not_found. La segunda es un endpoint público que no necesita clave de API. Su respuesta de ejemplo documentada muestra input_per_1m_tokens y output_per_1m_tokens para gpt-4o y ningún campo de caché. Su updated_at en esa muestra es 2026-04-20, que es dato de muestra, no precio actual. Para precios de caché, usamos el endpoint por modelo.

Para confirmar que el almacenamiento en caché funcionó, los objetos usage documentados son más delgados de lo que podrías esperar. Chat Completions lista prompt_tokens, completion_tokens y total_tokens. Messages lista input_tokens y output_tokens. Ninguna referencia nombra un campo de tokens en caché. La guía de costos de agentes de codificación (observada el 2026-10-03) dice que confirmes el uso de tokens en caché en la respuesta o en Usage, y que registres tokens de entrada, salida y caché por tarea.

Una prueba que ejecutaríamos:

1. Envía la misma solicitud de prefijo largo dos veces, con unos segundos de diferencia, cambiando solo el mensaje final del usuario.
2. Registra el objeto usage completo sin procesar de ambas respuestas, más el billing_transaction_id si está presente.
3. Compara el cargo de la segunda solicitud en Usage contra la aritmética anterior. Un acierto de caché debería aterrizar cerca de la cifra "con caché", no la de "sin caché".
4. Repite con una primera línea alterada deliberadamente para ver el costo de fallo.

Para Chat Completions en streaming, establece stream_options.include_usage: true para recibir el uso en los fragmentos del stream. Un encabezado de facturación puede estar ausente en los streams, así que usa Usage para el cargo final. La guía de resolución de problemas también describe GET /v1/management/api-keys/{keyId}/usage, que filtra por model, startDate y endDate para la reconciliación del lado del servidor.

Cuándo no vale la pena el costo de caché de prompts

El almacenamiento en caché es una apuesta al tráfico repetido. Pierde en estas situaciones:

• El prefijo nunca se repite. Un documento único de 20,000 tokens paga cualquier prima de escritura y no gana nada a cambio.
• Las solicitudes llegan demasiado lento. Si la brecha entre solicitudes coincidentes excede el tiempo de vida del caché, cada llamada es una escritura nueva. No encontramos ese tiempo de vida en la evidencia, así que mide tu propia brecha contra lo que indica la página del modelo.
• El prefijo cambia antes del límite. El sobregasto del 25% en el caso de fallo anterior proviene exactamente de este patrón.
• El prefijo es pequeño. Los ahorros escalan con los tokens de prefijo. Unos pocos cientos de tokens ahorran fracciones de centavo por llamada, y el tamaño mínimo almacenable en caché no está en la evidencia.
• La salida domina la factura. El caché recorta solo la entrada. Si las respuestas son largas, la línea de caché mueve una pequeña parte del total.
• El modelo no lista precio de caché. La guía de facturación dice que un guion en la columna de precios de TokenLab significa que no hay oferta verificada, no que sea gratis. Verifica el detalle de precios de un modelo antes de contar con cualquier descuento.

Patrón de carga de trabajo	Viabilidad de caché	Por qué
Bucles de herramientas de múltiples turnos	Alta	Las instrucciones y definiciones de herramientas permanecen fijas en los pasos.
Muchos usuarios consultando un documento grande	Alta	Las ráfagas de tráfico amortizan la escritura rápidamente.
Trabajos en segundo plano poco frecuentes	Baja	Las brechas más amplias que el tiempo de vida del caché fuerzan escrituras repetidas.
Prompts del sistema variables	Baja	Los cambios antes del límite rompen la coincidencia.

El almacenamiento en caché de prompts también difiere del consejo "Implementar caché" en la guía de facturación, que significa almacenar respuestas para solicitudes idénticas repetidas en tu propia aplicación. Eso evita la llamada al modelo por completo, pero solo ayuda cuando toda la solicitud se repite. Para sesiones largas de agentes, la guía de costos de agentes de codificación cubre el tamaño del contexto, los límites de salida y la elección del modelo junto con el almacenamiento en caché.

Preguntas frecuentes

¿Un acierto de caché siempre hace que una solicitud sea más barata?

Solo para el prefijo coincidente, y solo si el modelo lista un precio de lectura de caché. En los modelos que verificamos, una lectura cuesta del 2% al 10% de la entrada. El sufijo y todos los tokens de salida se facturan a tasas normales. Un fallo en un modelo con prima de escritura puede costar más que una llamada sin caché.

¿Un precio de escritura de caché faltante es lo mismo que gratis?

No. Para gpt-5.5 y gemini-3.8-flash, la API en vivo listó un precio de lectura de caché y ningún precio de escritura el 2026-10-03. Ejecuta una primera solicitud y lee el cargo en Usage en lugar de asumir cero o la tasa de entrada.

¿A dónde van los valores por usuario en un prompt almacenable en caché?

Ponlos después del contenido compartido, en el mensaje del usuario o en una entrada tardía de messages. Cualquier cosa que varíe antes del bloque compartido cambia el prefijo y fuerza una nueva escritura. Eso incluye marcas de tiempo, IDs de sesión y listas de herramientas reordenadas.

¿Por qué una solicitud repetida mostraría cero tokens en caché?

Verificaríamos cuatro cosas en orden. ¿El modelo lista prompt-cache? ¿El prefijo es idéntico en bytes entre llamadas? ¿La segunda llamada llegó dentro del tiempo de vida del caché? ¿El conteo en caché está en un campo que tu registro descarta? La documentación que leímos no nombra ese campo, así que registra el objeto usage completo.

Compara precios de caché en vivo antes de comprometerte con un modelo en la página de modelos de TokenLab.