Claude 캐시 과금

GPT/Gemini의 자동 캐시와 달리, Claude 네이티브 인터페이스의 프롬프트 캐시는 명시적 선언 방식입니다: cache_control로 캐시할 콘텐츠 블록을 표시합니다. 캐시 히트 시 해당 부분은 캐시 요금 배율로 과금됩니다.

사용법

system 또는 메시지 콘텐츠 블록에 cache_control을 추가합니다:

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "<수천 자의 규칙 문서 또는 지식 베이스>",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "규칙에 따라 답변하세요:……" }]
}

히트 확인

응답의 usage 필드에서 확인:

{
  "usage": {
    "input_tokens": 42,
    "cache_creation_input_tokens": 4810,
    "cache_read_input_tokens": 0,
    "output_tokens": 213
  }
}

• 최초 호출 시: cache_creation_input_tokens가 캐시 생성 비용으로 계산됩니다(표준 가격보다 약간 높음);
• 이후 히트 시: cache_read_input_tokens가 캐시 요금 배율로 과금됩니다(표준 가격보다 훨씬 저렴);
• 캐시 유효 기간은 분 단위이며, 지속적으로 호출하면 자동으로 갱신됩니다.

실용 권장 사항

• 캐시 포인트는 길고 안정적인 콘텐츠 뒤에 배치하세요: 시스템 프롬프트, 도구 정의, 참조 문서;
• 캐시된 콘텐츠는 바이트 단위로 완전히 일치해야 하므로, 템플릿에 타임스탬프 등 가변 필드를 혼용하지 마세요;
• 저빈도 호출(캐시 유효 기간을 초과하는 간격)은 히트되지 않으며, 반복적으로 캐시를 생성하면 오히려 비용이 더 높아집니다—— 저빈도 시나리오에서는 cache_control을 추가하지 마세요;
• OpenAI 호환 인터페이스를 통해 Claude를 호출할 경우 캐시는 업스트림에서 자동으로 처리되므로 해당 파라미터가 필요 없습니다, 캐시 과금을 참조하세요.