Caché de prompts de Claude

Documentation Index

Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt

Use this file to discover all available pages before exploring further.

curl https://aihubmix.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: AIHUBMIX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "stream": true,
    "model": "claude-opus-4-20250514",
    "max_tokens": 20000,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style."
      },
      {
        "type": "text",
        "text": "Pride and Prejudice by Jane Austen... [Place complete text content here]",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 16000
    },
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

​

Cómo funciona la caché de prompts

1. El sistema comprueba si un prefijo del prompt, hasta un punto de corte de caché especificado, ya está almacenado en caché de una consulta reciente.
2. Si lo encuentra, utiliza la versión en caché, reduciendo el tiempo de procesamiento y los costos.
3. De lo contrario, procesa el prompt completo y almacena en caché el prefijo cuando 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

​

Precios

• Los tokens de escritura en caché de 5 minutos cuestan 1,25 veces el precio de los tokens de entrada base
• Los tokens de escritura en caché de 1 hora cuestan 2 veces el precio de los tokens de entrada base
• Los tokens de lectura de caché cuestan 0,1 veces el precio de los tokens de entrada base
• Los tokens regulares de entrada y salida tienen los precios estándar de la plataforma

​

Cómo implementar la caché de prompts

​

Modelos admitidos

• Claude Opus 4
• Claude Sonnet 4
• Claude Sonnet 3.7
• Claude Sonnet 3.5
• Claude Haiku 3.5
• Claude Haiku 3
• Claude Opus 3

​

Estructuración de tu prompt

​

Limitaciones de la caché

• 1024 tokens para Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 y Claude Opus 3
• 2048 tokens para Claude Haiku 3.5 y Claude Haiku 3

• “ephemeral”: Vida útil predeterminada de 5 minutos
• Caché de 1 hora (Beta): Para escenarios que requieran una duración de caché más larga

​

Duración de caché de 1 hora (Beta)

curl https://aihubmix.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: AIHUBMIX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: extended-cache-ttl-2025-04-11" \
  -d '{
    "model": "claude-opus-4-20250514",
    "system": [
      {
        "type": "text",
        "text": "Long-term instructions...",
        "cache_control": {
          "type": "ephemeral",
          "ttl": "1h"
        }
      }
    ],
    "messages": [...]
  }'

{
  "cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
  }
}

​

Cuándo usar la caché de 1 hora

• Procesamiento por lotes: Procesar grandes volúmenes de solicitudes con prefijos comunes
• Sesiones de larga duración: Conversaciones que requieren mantener el contexto durante periodos prolongados
• Análisis de documentos grandes: Múltiples tipos diferentes de análisis sobre el mismo documento
• Preguntas y respuestas sobre código: Múltiples consultas sobre la misma base de código a lo largo de periodos prolongados

​

Combinando distintos TTL

{
  "system": [
    {
      "type": "text", 
      "text": "Long-term instructions...",
      "cache_control": {
        "type": "ephemeral",
        "ttl": "1h"
      }
    },
    {
      "type": "text",
      "text": "Short-term context...", 
      "cache_control": {
        "type": "ephemeral",
        "ttl": "5m"
      }
    }
  ]
}

​

Qué se puede almacenar en caché

• Herramientas: Definiciones de herramientas en el array tools
• Mensajes del sistema: Bloques de contenido en el array system
• Mensajes: Bloques de contenido en el array messages.content, tanto en los turnos del usuario como en los del asistente
• Imágenes y documentos: Bloques de contenido en el array messages.content, en los turnos del usuario
• Uso de herramientas y resultados de herramientas: Bloques de contenido en el array messages.content, tanto en los turnos del usuario como en los del asistente

​

Qué no se puede almacenar en caché

• Los bloques de razonamiento (thinking) no pueden almacenarse en caché directamente con cache_control. Sin embargo, los bloques de razonamiento SÍ pueden almacenarse en caché junto con otro contenido cuando aparecen en turnos anteriores del asistente. Cuando se almacenan así, SÍ cuentan como tokens de entrada cuando se leen de la caché.
• Los subbloques de contenido (como las citas) no pueden almacenarse en caché directamente por sí mismos. En su lugar, almacena en caché el bloque de nivel superior.
• Los bloques de texto vacíos no se pueden almacenar en caché.

​

Seguimiento del rendimiento de la caché

• 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 desde la caché ni se usaron para crear una caché.

​

Buenas prácticas para una caché eficaz

• Almacena en caché contenido estable y reutilizable como instrucciones del sistema, información de fondo, contextos extensos o definiciones de herramientas frecuentes.
• Coloca el contenido en caché al principio del prompt para obtener el mejor rendimiento.
• Usa los puntos de corte de caché de forma estratégica para separar distintas secciones de prefijo cacheables.
• Analiza regularmente las tasas de acierto de caché y ajusta tu estrategia según sea necesario.
• Para contenido a largo plazo, considera usar la caché de 1 hora para una mejor eficiencia de costos.

​

Optimización para distintos casos de uso

• 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 material extenso completo, incluidas imágenes, en tu prompt sin aumentar la latencia de la respuesta.
• Conjuntos de instrucciones detallados: Comparte listas exhaustivas de instrucciones, procedimientos y ejemplos para afinar las respuestas de Claude. Los desarrolladores suelen incluir uno o dos ejemplos en el prompt, pero con la caché de prompts puedes obtener un rendimiento aún mejor incluyendo más de 20 ejemplos diversos de respuestas de alta calidad.
• Uso agentic de herramientas: Mejora el rendimiento en escenarios que involucran múltiples llamadas a herramientas y cambios iterativos de código, donde cada paso suele requerir una nueva llamada a la API.
• Conversar con libros, papers, documentación, transcripciones de podcasts y otro contenido extenso: Da vida a cualquier base de conocimiento incrustando los documentos completos en el prompt y dejando que los usuarios hagan preguntas.

​

Solución de problemas comunes

• Asegúrate de que las secciones cacheadas sean idénticas y estén marcadas con cache_control en las mismas ubicaciones en todas las llamadas
• Comprueba que las llamadas se realicen dentro de la vida útil de la caché (5 minutos o 1 hora)
• Verifica que tool_choice y el uso de imágenes se mantengan consistentes entre las llamadas
• Valida que estás almacenando en caché al menos el número mínimo de tokens
• Aunque el sistema intentará utilizar el contenido cacheado previamente en las posiciones anteriores a un punto de corte de caché, puedes usar un parámetro cache_control adicional para garantizar la búsqueda en caché en porciones previas del prompt, lo que puede ser útil en consultas con listas muy largas de bloques de contenido

​

Almacenamiento y compartición de la caché

• Aislamiento por organización: Las cachés están aisladas entre organizaciones. Distintas organizaciones nunca comparten cachés, incluso si usan prompts idénticos.
• Coincidencia exacta: Los aciertos de caché requieren segmentos de prompt 100 % idénticos, incluido todo el texto e imágenes hasta el bloque marcado con cache_control. El mismo bloque debe marcarse con cache_control tanto en la lectura como en la creación de la caché.
• Generación de tokens de salida: La caché de prompts no afecta a la generación de tokens de salida. La respuesta que recibirás será idéntica a la que obtendrías sin caché de prompts.

​

Soporte en distintos modelos

• Si Prompt Caching está admitido o no depende del propio modelo.
• Si el modelo admite inherentemente la caché sin necesidad de declaraciones de parámetros explícitas, puede admitirse mediante el reenvío compatible con OpenAI.
• OpenAI admite Prompt Caching por defecto. Los prompts cacheados no se facturan, la recuperación de tokens cacheados cuesta la mitad de la tarifa normal y las cachés se borran automáticamente tras 5-10 minutos de inactividad. Detalles
• Claude requiere la declaración nativa cache_control: { type: "ephemeral" }. La tasa de almacenamiento es 1,25 veces el costo de entrada estándar (5 minutos) o 2 veces (1 hora), la recuperación de tokens cacheados cuesta 0,1 veces la tarifa normal, con un ciclo de vida de 5 minutos o 1 hora. Detalles
• Deepseek V3 y R1 admiten la caché de forma nativa. La tasa de almacenamiento equivale al costo de entrada estándar y la recuperación de tokens cacheados cuesta 0,1 veces la tarifa normal. Detalles
• Soporte de caché implícita de Gemini:
  • Caché implícita: Habilitada por defecto para todos los modelos Gemini 2.5. Si tu solicitud acierta en la caché, los ahorros de costo se aplican automáticamente. Esta función entró en vigor el 8 de mayo de 2025. El recuento mínimo de tokens de entrada para la caché de contexto es de 1.024 para Gemini 2.5 Flash y de 2.048 para Gemini 2.5 Pro.
  • Consejos para mejorar la tasa de aciertos de la caché implícita:
    • Intenta colocar al principio del prompt el contenido extenso y de uso frecuente.
    • Intenta enviar solicitudes con prefijos similares dentro de una ventana de tiempo corta.
  • Puedes ver el número de tokens con acierto de caché en el campo usage_metadata del objeto de respuesta.
  • Los ahorros de costos se calculan según los aciertos de caché en prefill. Solo la caché de prefill y la caché de preprocesamiento de vídeo de YouTube son elegibles para la caché implícita.