Claude コンテキストキャッシュ利用ガイド

export API_KEY="あなたの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": "ここに繰り返し使用する長いプレフィックスを入力します……",
        "cache_control": {
          "type": "ephemeral"
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "上記の内容に基づいて質問に回答してください。"
      }
    ]
  }'

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": "ここに繰り返し使用する長いプレフィックスを入力します……",
        "cache_control": {
          "type": "ephemeral",
          "ttl": "1h"
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "上記の内容に基づいて質問に回答してください。"
      }
    ]
  }'

{
  "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": "ここに繰り返し使用する長いプレフィックスを入力します……",
            "cache_control": {
              "type": "ephemeral"
            }
          }
        ]
      },
      {
        "role": "user",
        "content": "上記の内容に基づいて質問に回答してください。"
      }
    ]
  }'

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

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

{
  "role": "system",
  "content": "ここに長いプレフィックスを入力します……",
  "cache_control": {
    "type": "ephemeral"
  }
}

{
  "role": "system",
  "content": [
    {
      "type": "text",
      "text": "ここに長いプレフィックスを入力します……",
      "cache_control": {
        "type": "ephemeral"
      }
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "ここに繰り返し使用する長いドキュメントを入力します……",
      "cache_control": {
        "type": "ephemeral"
      }
    },
    {
      "type": "text",
      "text": "上記のドキュメントから 3 つの主要なポイントを要約してください。"
    }
  ]
}

{
  "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 = (
    "プロンプトキャッシュはリクエストのプレフィックスを保存するため、後続のリクエストで "
    "バイト単位で同一のプレフィックスを再処理せずに利用できます。 "
)

system_text = (
    "あなたはドキュメント作成アシスタントです。参考資料を以下に示します。\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": "変更せずに維持する必要があるものを 1 文で答えてください。"
    }]
}))
PY

for request_number in 1 2; do
  echo "${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

1 回目のリクエスト：cache_creation_input_tokens > 0、cache_read_input_tokens = 0
2 回目のリクエスト：cache_creation_input_tokens = 0、cache_read_input_tokens > 0