Domine los 3 puntos clave de la facturación por caché de Claude: por qué debe usar el formato nativo de Anthropic para la invocación

Muchos desarrolladores se encuentran con un dilema al usar la API de Claude: a pesar de haber activado el prompt caching, ¿por qué no aparecen los descuentos por caché en la factura?

La respuesta suele ser muy sencilla: estás utilizando la invocación en modo compatible con OpenAI, mientras que la facturación por caché de Claude solo es compatible con el formato nativo de la Messages API de Anthropic.

No se trata de un error, sino de una limitación de diseño especificada claramente en la documentación oficial de Anthropic. En este artículo, analizaremos los principios técnicos, los métodos de invocación y la comparativa de precios para ayudarte a entender a fondo el uso correcto del prompt caching de Claude y evitar gastos innecesarios.

Principios básicos del mecanismo de Claude Prompt Caching

Antes de profundizar en las diferencias de formato, es fundamental entender cómo funciona el prompt caching de Claude.

¿Cómo funciona el caché de Claude?

Cuando envías una solicitud con el prompt caching activado, el sistema sigue este proceso:

1. Verificación de caché: El sistema comprueba si el prefijo de la indicación ya ha sido almacenado en una consulta reciente.
2. Acierto de caché (Cache Hit): Si se encuentra una coincidencia, se utiliza la versión almacenada, reduciendo drásticamente el tiempo de procesamiento y el coste.
3. Escritura en caché (Cache Write): Si no hay coincidencia, se procesa la indicación completa y se almacena el prefijo una vez que comienza la respuesta.

Contenido compatible con el prompt caching de Claude

Claude prompt caching permite almacenar la mayoría de los bloques de contenido de una solicitud:

• Tools: Definiciones de herramientas en el array tools.
• Mensajes de sistema: Bloques de contenido en el array system.
• Mensajes de texto: Bloques de contenido de texto en messages.content.
• Imágenes y documentos: Imágenes y documentos dentro de los mensajes del usuario.
• Uso y resultados de herramientas: Bloques de contenido con llamadas a herramientas y sus respectivos resultados.

🎯 Consejo técnico: Para escenarios que requieren invocaciones frecuentes con la misma indicación de sistema, el prompt caching es la herramienta de optimización de costes más efectiva. Recomendamos utilizar el formato nativo de Anthropic a través de la plataforma APIYI (apiyi.com) para aprovechar al máximo los descuentos en la facturación de caché.

Formato nativo de Anthropic vs. modo de compatibilidad de OpenAI: Diferencias en el soporte de caché de Claude

Esta es la parte más importante de este artículo: la diferencia fundamental entre los dos formatos de invocación en lo que respecta a la función de caché de Claude.

Declaración oficial de Anthropic

Según el texto original de la documentación de compatibilidad del SDK de OpenAI de Anthropic:

"Prompt caching is not supported, but it is supported in the Anthropic SDK"
(El almacenamiento en caché de indicaciones no es compatible, pero sí lo es en el SDK de Anthropic)

Esto significa que, si invocas a Claude a través del modo de compatibilidad de OpenAI (punto de conexión /v1/chat/completions), no podrás utilizar la función de prompt caching en absoluto.

Comparativa de funciones entre los dos formatos de invocación de la API de Claude

Por qué el modo de compatibilidad de OpenAI no admite el caché de Claude

El modo de compatibilidad de OpenAI está diseñado para probar y comparar las capacidades del modelo, no para su uso en entornos de producción:

1. Diferencias de protocolo: El parámetro cache_control es un campo nativo de la API de Messages de Anthropic que no tiene un campo correspondiente en el formato de chat completions de OpenAI.
2. Limitaciones de arquitectura: La capa de compatibilidad necesita convertir el formato de OpenAI al formato de Anthropic; durante este proceso, la información de control de caché se pierde.
3. Prioridades: Anthropic ha declarado que la prioridad de la capa de compatibilidad es inferior a la fiabilidad y la integridad funcional de la API nativa de Claude.

💡 Nota importante: Si tu negocio depende del prompt caching para controlar costos, debes utilizar el formato nativo de la API de Messages de Anthropic, en lugar del modo de compatibilidad de OpenAI.

Detalles de precios del Prompt Caching de Claude: Ahorre hasta un 90% en costos

La estructura de precios del prompt caching de Claude es su aspecto más atractivo: el precio de lectura de un acierto de caché (hit) es solo el 10% del precio de entrada base.

Comparativa de precios de caché para todos los modelos de Claude

MTok = Millón de Tokens. Fuente de datos: Página oficial de precios de Anthropic (febrero de 2026)

Reglas de cálculo de precios de caché de Claude

Los precios de caché siguen tres reglas sencillas de multiplicación:

• Escritura de caché de 5 minutos: Precio de entrada base × 1.25
• Escritura de caché de 1 hora: Precio de entrada base × 2.0
• Lectura de caché (hit): Precio de entrada base × 0.1

Tomando como ejemplo a Claude Sonnet 4.6, supongamos que tienes una indicación de sistema de 100,000 tokens:

💰 Optimización de costos: Para escenarios donde se reutiliza la misma indicación de sistema (system prompt), invocar la API de Claude en su formato nativo a través de la plataforma APIYI (apiyi.com) permite aprovechar al máximo el prompt caching y lograr un ahorro de costos de hasta el 90%.

A continuación, a través de ejemplos de código concretos, te muestro cómo habilitar correctamente el prompt caching de Claude.

Ejemplo de invocación básica: Formato nativo de Anthropic + Extended Thinking

curl https://api.apiyi.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 16000,
    "stream": false,
    "thinking": {
      "type": "enabled",
      "budget_tokens": 10000
    },
    "messages": [
      {
        "role": "user",
        "content": "¿Cuánto es 27 * 453?"
      }
    ]
  }'

Arriba tienes una invocación básica en el formato nativo de Anthropic, utilizando la función de Extended Thinking. Ahora veamos cómo habilitar el prompt caching sobre esta base.

Modo de caché automático: La forma más sencilla de activar el caché de Claude

El caché automático es la manera más fácil de habilitar el prompt caching de Claude; solo tienes que añadir el campo cache_control en el nivel superior del cuerpo de la solicitud:

curl https://api.apiyi.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral"},
    "system": "Eres un asistente profesional de documentación técnica que ayuda a los usuarios a entender los métodos de uso y las mejores prácticas de los modelos de IA. Tus respuestas deben ser precisas, concisas y útiles.",
    "messages": [
      {"role": "user", "content": "¿Cuáles son las principales características de Claude Sonnet 4.6?"},
      {"role": "assistant", "content": "Claude Sonnet 4.6 es un modelo de alto rendimiento lanzado por Anthropic..."},
      {"role": "user", "content": "¿Qué tan grande es su ventana de contexto?"}
    ]
  }'

En el modo de caché automático, el sistema coloca automáticamente el punto de interrupción del caché en el último bloque de contenido que se pueda almacenar. En conversaciones de varias rondas, el punto de caché avanzará automáticamente a medida que crezca el diálogo.

Modo de caché explícito: Control preciso sobre el contenido en caché de Claude

Para escenarios que requieren un control detallado del comportamiento del caché, puedes colocar cache_control en bloques de contenido específicos:

curl https://api.apiyi.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "Eres un asistente de análisis de documentos legales, experto en analizar cláusulas contractuales y riesgos legales."
      },
      {
        "type": "text",
        "text": "[Aquí se inserta el texto completo de un contrato legal de 50 páginas... aproximadamente 100,000 tokens de contenido]",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Por favor, analiza las cláusulas clave y los riesgos potenciales de este contrato."
      }
    ]
  }'

En este ejemplo, una gran cantidad de documentos legales se marca como contenido en caché. La primera solicitud escribirá en el caché; durante los siguientes 5 minutos, cualquier consulta sobre diferentes preguntas del mismo documento acertará en el caché, y solo tendrás que pagar el 10% del coste de lectura.

Caché de larga duración de 1 hora: Ampliando el tiempo de caché de Claude

Si el tiempo de caché predeterminado de 5 minutos no es suficiente, puedes optar por el caché de 1 hora:

"cache_control": {"type": "ephemeral", "ttl": "1h"}

El caché de 1 hora es ideal para:

• Tareas de larga duración en flujos de trabajo de agentes (más de 5 minutos)
• Escenarios donde el intervalo entre diálogos del usuario puede superar los 5 minutos
• Escenarios que requieren una mayor utilización del límite de tasa (los aciertos en caché no descuentan del rate limit)

🚀 Inicio rápido: Te recomendamos usar la plataforma APIYI (apiyi.com) para probar rápidamente la función de prompt caching de Claude. La plataforma es totalmente compatible con el formato nativo de la API de Messages de Anthropic, incluyendo el parámetro cache_control, permitiéndote completar la validación de la integración en solo 5 minutos.

Monitoreo y depuración del rendimiento del caché de Claude

Una vez habilitado el caché, es necesario monitorear su efectividad a través del campo usage en la respuesta de la API.

Campos clave en la respuesta de caché de Claude

{
  "usage": {
    "input_tokens": 50,
    "cache_creation_input_tokens": 100000,
    "cache_read_input_tokens": 0,
    "output_tokens": 500
  }
}

Fórmula de cálculo del total de tokens de entrada:

total_input = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

Solución de problemas comunes cuando el caché de Claude no funciona

Si notas que el caché no se activa nunca, revisa los siguientes puntos:

1. Formato de invocación incorrecto: Se usó el modo de compatibilidad de OpenAI en lugar del formato nativo de Anthropic.
2. Contenido inconsistente: La coincidencia de caché requiere un prefijo de indicación 100% idéntico.
3. Tokens insuficientes: No se alcanzó el requisito mínimo de tokens de caché del modelo.
4. Expiración por tiempo: El caché caducó tras más de 5 minutos sin uso.
5. Cambio de parámetros: Se modificó tool_choice, el contenido de la imagen o los parámetros de thinking.

Requisitos mínimos de tokens de caché para cada modelo de Claude

Si tu indicación no alcanza el número mínimo de tokens, el cache_control no tendrá efecto aunque esté marcado; la solicitud se procesará normalmente pero no se guardará en el caché.

🎯 Consejo de depuración: Al invocar la API de Claude en la plataforma APIYI (apiyi.com), puedes determinar rápidamente si el caché está funcionando a través del campo usage en la respuesta. Si tanto cache_read_input_tokens como cache_creation_input_tokens son 0, significa que la función de caché no se ha habilitado correctamente.

Claude Prompt Caching: Preguntas frecuentes (FAQ)

Q1: ¿Puedo usar el almacenamiento en caché al invocar Claude en el modo de compatibilidad con OpenAI?

No. Esta es una limitación declarada explícitamente por Anthropic. El modo de compatibilidad con OpenAI (endpoint /v1/chat/completions) no admite el prompt caching. Debes utilizar el formato nativo de la API de Messages de Anthropic (endpoint /v1/messages) para poder disfrutar de las funciones de caché.

A través de la plataforma APIYI (apiyi.com), puedes realizar llamadas a la API de Claude utilizando ambos formatos; si necesitas la función de caché, simplemente elige el endpoint /v1/messages.

Q2: La escritura en caché de Claude es más cara que la entrada normal, ¿realmente vale la pena?

Absolutamente. La escritura en caché es solo un 25% más cara que la entrada básica (con un TTL de 5 minutos), pero un acierto de caché (cache hit) cuesta solo el 10% del precio estándar. En cuanto el mismo contenido se utiliza más de 2 veces, ya habrás amortizado el coste y empezarás a ahorrar dinero. Tomando como ejemplo una indicación de sistema (system prompt) de 100,000 tokens:

• Sin caché: $0.30 por cada vez (Sonnet 3.5)
• Escritura en caché: $0.375 (solo la primera vez)
• Lectura de caché: $0.03 (cada vez posterior)
• Empezarás a ahorrar a partir de la segunda invocación.

Q3: ¿Cómo migrar del formato de OpenAI al formato nativo de Anthropic en mi código?

Los puntos clave del cambio son:

• Endpoint: /v1/chat/completions → /v1/messages
• Encabezados (Headers): Añadir anthropic-version: 2023-06-01
• Formato de mensajes: La estructura del array messages es básicamente la misma.
• Indicación de sistema (System prompt): Se extrae de messages a un campo independiente llamado system.
• Añadir el parámetro cache_control.

La plataforma APIYI (apiyi.com) admite ambos endpoints simultáneamente. Al migrar, solo necesitas modificar la ruta y el formato de la solicitud, sin necesidad de cambiar tu clave API.

Q4: ¿Se puede compartir el caché de Claude entre diferentes solicitudes?

El caché se comparte dentro del mismo Workspace (a partir del 5 de febrero de 2026, el aislamiento pasó de ser a nivel de organización a nivel de Workspace). El caché nunca se comparte entre diferentes organizaciones.

Q5: ¿Se pueden usar de forma combinada el caché y la API de Batch?

Sí. La API de Batch ofrece un 50% de descuento, y los multiplicadores de precio del caché se aplican sobre esa base. La combinación de ambos permite maximizar la optimización de costes. Se recomienda usar un TTL de caché de 1 hora en escenarios de procesamiento por lotes para mejorar la tasa de aciertos.

Resumen: 3 puntos clave sobre la facturación de Claude Prompt Caching

Tras analizar el funcionamiento del prompt caching de Claude, estos son los 3 puntos fundamentales que debes recordar:

1. Solo admite el formato nativo de Anthropic: La función de caché solo está disponible en el endpoint /v1/messages; el modo de compatibilidad con OpenAI (/v1/chat/completions) no la admite.
2. El coste del acierto de caché es solo del 10%: Pagas un 25% más en la primera escritura, pero cada acierto posterior cuesta solo una décima parte del precio base. Se amortiza en solo 2 llamadas.
3. La forma de invocación es la clave: Utiliza el parámetro cache_control: {"type": "ephemeral"} y asegúrate de cumplir con el requisito mínimo de tokens de caché del modelo.

Te recomendamos probar todas las funciones de Claude prompt caching a través de la plataforma APIYI (apiyi.com). Esta plataforma ofrece soporte completo para la API de Messages nativa de Anthropic, ayudándote a utilizar los modelos de Claude con el coste más eficiente.

Referencias

1. Documentación oficial de Anthropic sobre Prompt Caching: Detalles de la función de caché de la API de Claude

   • Enlace: platform.claude.com/docs/en/build-with-claude/prompt-caching

2. Página oficial de precios de Anthropic: Precios de los modelos Claude y del almacenamiento en caché

   • Enlace: platform.claude.com/docs/en/about-claude/pricing

3. Documentación de compatibilidad con el SDK de OpenAI: Explicación de las limitaciones de las funciones en modo compatible

   • Enlace: platform.claude.com/docs/en/api/openai-sdk

📝 Autor: APIYI Team | Equipo técnico de APIYI, especializados en la integración de API de Modelos de Lenguaje Grande y en compartir conocimientos técnicos. Visita apiyi.com para obtener más tutoriales técnicos.