Guía de uso de la caché de contexto de Claude

export API_KEY="TU_CLAVE_API"

curl "https://api.apimart.ai/v1/messages" \
  -H "x-api-key: $API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "Aquí se incluye el prefijo largo que se reutilizará…",
        "cache_control": {
          "type": "ephemeral"
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Responde a la pregunta a partir del contenido anterior."
      }
    ]
  }'

curl "https://api.apimart.ai/v1/messages" \
  -H "x-api-key: $API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: extended-cache-ttl-2025-04-11" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "Aquí se incluye el prefijo largo que se reutilizará…",
        "cache_control": {
          "type": "ephemeral",
          "ttl": "1h"
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Responde a la pregunta a partir del contenido anterior."
      }
    ]
  }'

{
  "usage": {
    "input_tokens": 23,
    "cache_creation_input_tokens": 2619,
    "cache_read_input_tokens": 0,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 2619,
      "ephemeral_1h_input_tokens": 0
    },
    "output_tokens": 24
  }
}

input_tokens
+ cache_creation_input_tokens
+ cache_read_input_tokens

curl "https://api.apimart.ai/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "system",
        "content": [
          {
            "type": "text",
            "text": "Aquí se incluye el prefijo largo que se reutilizará…",
            "cache_control": {
              "type": "ephemeral"
            }
          }
        ]
      },
      {
        "role": "user",
        "content": "Responde a la pregunta a partir del contenido anterior."
      }
    ]
  }'

-H "anthropic-beta: extended-cache-ttl-2025-04-11"

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

{
  "role": "system",
  "content": "Aquí se incluye el prefijo largo…",
  "cache_control": {
    "type": "ephemeral"
  }
}

{
  "role": "system",
  "content": [
    {
      "type": "text",
      "text": "Aquí se incluye el prefijo largo…",
      "cache_control": {
        "type": "ephemeral"
      }
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "Aquí se incluye el documento largo que se reutilizará…",
      "cache_control": {
        "type": "ephemeral"
      }
    },
    {
      "type": "text",
      "text": "Resume los tres puntos principales del documento anterior."
    }
  ]
}

{
  "usage": {
    "prompt_tokens": 1942,
    "completion_tokens": 22,
    "prompt_tokens_details": {
      "cached_tokens": 1921,
      "cache_write_tokens": 0
    },
    "claude_cache_creation_5_m_tokens": 0,
    "claude_cache_creation_1_h_tokens": 0
  }
}

python3 - <<'PY' > /tmp/claude-cache-request.json
import json

paragraph = (
    "Prompt caching stores a prefix of the request so that later requests "
    "can reuse the same byte-identical prefix without processing it again. "
)

system_text = (
    "You are a documentation assistant. Reference material follows.\n\n"
    + paragraph * 40
)

print(json.dumps({
    "model": "claude-sonnet-5",
    "max_tokens": 32,
    "system": [{
        "type": "text",
        "text": system_text,
        "cache_control": {"type": "ephemeral"}
    }],
    "messages": [{
        "role": "user",
        "content": "In one sentence, what must remain unchanged?"
    }]
}))
PY

for request_number in 1 2; do
  echo "Solicitud ${request_number}"
  curl -s "https://api.apimart.ai/v1/messages" \
    -H "x-api-key: $API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "Content-Type: application/json" \
    --data @/tmp/claude-cache-request.json \
  | python3 -c "import json, sys; print(json.load(sys.stdin)['usage'])"
done

Solicitud 1: cache_creation_input_tokens > 0, cache_read_input_tokens = 0
Solicitud 2: cache_creation_input_tokens = 0, cache_read_input_tokens > 0