Caché de prompts

La mayoría de las solicitudes se repiten: el mismo system prompt, las mismas definiciones de herramientas, el mismo documento largo, la misma conversación hasta el momento. La caché de prompts permite que el modelo reutilice el trabajo que ya hizo sobre ese comienzo repetido, y pagas una fracción del precio de entrada por la parte en caché.

Es especialmente útil para agentes de programación y apps de chat, que reenvían casi todo su contexto en cada turno.

Cómo se cobra

Cada modelo con caché tiene un precio cached_input junto a su precio de entrada, en la lista de modelos y en su página del modelo. Por ejemplo, claude-sonnet-4-6 cobra $3 por 1M de tokens de entrada y $0.30 por 1M de tokens de entrada en caché. Algunos modelos también cobran más que el precio de entrada por escribir una entrada en caché la primera vez; su página lo indica.

Los tokens en caché aparecen en el uso y en tus logs de solicitudes:

"usage": {
  "prompt_tokens": 12850,
  "completion_tokens": 210,
  "prompt_tokens_details": { "cached_tokens": 12288 }
}

En el endpoint Messages son cache_read_input_tokens y cache_creation_input_tokens.

Caché automática

Muchos modelos —incluidas las familias GPT, Gemini, DeepSeek y Kimi— usan la caché automáticamente. No tienes que cambiar nada: cuando una solicitud empieza con los mismos tokens que una reciente, el prefijo compartido se sirve desde la caché. Para aprovecharla al máximo:

• Pon primero lo que no cambia: system prompt, definiciones de herramientas, documentos de referencia.
• Pon al final lo que cambia: el mensaje más reciente del usuario.
• No pongas timestamps ni IDs de solicitud en el system prompt; un solo token distinto al principio rompe la coincidencia de todo lo que viene después.

Caché explícita con cache_control

Los modelos Claude solo guardan en caché lo que marcas. Agrega un breakpoint cache_control al último bloque de la parte que quieres reutilizar, y todo hasta ese punto queda en caché:

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "You are a support agent for Acme. Here is the full product manual: ...",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "How do I reset the device?" }]
}

El mismo marcador funciona en Chat Completions, en una parte de texto de un mensaje:

{
  "role": "system",
  "content": [
    { "type": "text", "text": "Long, stable instructions...", "cache_control": { "type": "ephemeral" } }
  ]
}

• Una entrada en caché dura cinco minutos por defecto y se renueva cada vez que se usa. "ttl": "1h" la conserva una hora, con un precio de escritura más alto.
• Hasta cuatro breakpoints por solicitud. Si marcas por separado las definiciones de herramientas y el system prompt, puedes cambiar uno sin perder el otro.
• Por debajo de una longitud mínima que depende del modelo (unos 1024 tokens en la mayoría de los modelos Claude), no se guarda nada en caché. La solicitud igual se completa correctamente.

Claude Code y la mayoría de los agentes de programación colocan estos marcadores por ti.

Verificar que funciona

Envía el mismo prompt largo dos veces en pocos minutos. La segunda respuesta debería reportar la mayor parte del prompt como tokens en caché. Si no reporta ninguno, busca algo que cambie al inicio del prompt entre una solicitud y otra.