작동 방식
Claude 프롬프트 캐싱으로 비용 줄이기
시스템 프롬프트, 파일, 도구 정의처럼 같은 큰 컨텍스트를 반복해서 보낸다면, 캐싱이 그 토큰을 비싼 것에서 거의 공짜로 바꿔줍니다.
·
캐싱이 비용을 아끼는 원리
캐시 쓰기와 캐시 읽기는 별도로 측정되며, 캐시 읽기는 새 입력 토큰의 일부 비용입니다. 안정적이고 재사용되는 컨텍스트가 이상적인 대상입니다.
함께 보기: Claude API에서 토큰을 절약하는 방법
네이티브 및 OpenAI 호환 요청
cache_control이 없거나 null이면 네이티브 Messages, Chat Completions, Responses의 Claude 요청에 5분 프롬프트 캐시가 자동으로 추가됩니다. 네이티브 Messages에서는 콘텐츠 블록에 명시적인 중단점을 넣을 수 있습니다. OpenAI 호환 경로에서는 cache_control을 요청 최상위 사용자 지정 확장으로 전달합니다.
- 1시간 TTL은 cache_control: {type: "ephemeral", ttl: "1h"}와 anthropic-beta: extended-cache-ttl-2025-04-11 헤더를 함께 보냅니다.
- OpenAI SDK에서는 extra_body로 확장을, extra_headers로 beta 헤더를 전달합니다.
- Chat Completions 캐시 적중은 usage.prompt_tokens_details.cached_tokens에 표시됩니다.
- Responses 캐시 적중은 usage.input_tokens_details.cached_tokens에 표시됩니다.
- 이 확장은 anthropic/* catalog plane 모델에만 적용됩니다.
할인과 겹쳐집니다
캐싱은 토큰 개수를 낮추고, apiToken.sale 할인은 토큰당 가격을 낮춥니다. 둘이 합쳐지면 청구액이 훨씬 작아지며, 모든 캐시 항목이 사용량 내역에 표시됩니다.
자주 묻는 질문
프롬프트 캐싱은 얼마나 절약되나요?
캐시 읽기는 새 입력 토큰의 일부 비용이므로, 반복되는 큰 컨텍스트가 훨씬 저렴해집니다.
캐싱이 할인과 함께 작동하나요?
네 — 캐싱은 토큰 개수를 줄이고 할인은 토큰당 가격을 줄이므로 절감 효과가 곱해집니다.
OpenAI 호환 Claude 경로에서도 캐싱이 작동하나요?
네. Chat Completions와 Responses는 기본 5분 캐시를 자동으로 사용하며, 최상위 cache_control 확장과 extended-cache beta 헤더로 1시간 TTL을 선택할 수 있습니다.