Claude 프롬프트 캐싱으로 API 비용 60% 절감한 실전 가이드

지난달 Claude API 청구서를 열어보니 $243이 찍혀 있었어요. 같은 시스템 프롬프트 8만 토큰을 매번 통째로 보내고 있었다는 걸 그제야 깨달았죠. 프롬프트 캐싱을 켜자 다음 달 청구서는 $92로 내려왔습니다. 62% 절감이었습니다.

이 글을 읽고 나면 여러분도 5분 안에 프롬프트 캐싱을 설정하고, 다음 달부터 API 비용을 절반 이하로 줄일 수 있게 됩니다. 9만 토큰 문서를 하루 50회 호출하는 실제 케이스 기준으로 비용을 계산해드릴게요.

준비물

시작하기 전에 다음이 필요합니다.

• Anthropic API 키 (공식 페이지에서 발급·요금 확인)
• Claude API 호출 코드 (Python·Node.js 등 어떤 언어든 가능)
• 반복 사용할 시스템 프롬프트 또는 긴 문맥 (최소 1024 토큰 이상 권장)

버전은 Claude 3 이상 모든 모델이 지원합니다. 제가 테스트한 환경은 Claude 3.5 Sonnet과 Python SDK였어요.

프롬프트 캐싱은 어떻게 설정하나요?

1단계: 캐시 대상 결정하기

먼저 반복되는 프리픽스를 찾아야 합니다. 시스템 프롬프트·문서·tools 정의처럼 요청마다 똑같이 들어가는 부분이죠.

핵심은 토큰 수입니다. 최소 1024~4096 토큰은 넘어야 캐싱이 동작해요. 짧으면 조용히 무시되는데 오류는 안 나서 착각하기 쉽습니다. 저는 처음에 2000 토큰짜리 프롬프트를 넣었다가 캐시가 안 먹혔던 경험이 있어요. 모델별 최소치를 공식 문서에서 확인하세요.

입력 예시: 8만 토큰짜리 제품 가이드 문서를 시스템 프롬프트에 넣음 결과: 이 블록 끝에 cache_control 표시 추가 대상으로 선정

2단계: cache_control 블록 삽입

이제 JSON 필드를 추가합니다. system·messages 각 콘텐츠 블록 끝에 다음 객체를 붙이면 됩니다.

{
  "type": "text",
  "text": "긴 시스템 프롬프트 내용...",
  "cache_control": {"type": "ephemeral"}
}

이 위치까지가 캐시 브레이크포인트가 되는 거예요. 요청당 최대 4개까지 브레이크포인트를 둘 수 있습니다. 기본 TTL은 5분이고, "ttl": "1h" 옵션으로 1시간까지 늘릴 수 있어요.

입력 예시: 시스템 프롬프트 끝에 cache_control 추가 결과: 첫 요청에서 캐시 쓰기 발생, 이후 5분 내 같은 프리픽스 요청 시 캐시 읽기

3단계: 비용 실제로 계산하기

9만 토큰 시스템 프롬프트를 하루 50회 호출하는 경우를 봅시다. Claude Sonnet 입력 단가는 $3/백만 토큰입니다 (출처: Anthropic 공식 모델 가격 문서).

캐시 없이: 9만 토큰 × 50회 × $3/백만 = $13.5/일

5분 TTL 캐시 사용 (출처: Anthropic Claude API Prompt Caching 공식 문서):

• 첫 요청 (캐시 쓰기): 9만 토큰 × 1.25배 = 11.25만 토큰 쓰기 비용
• 이후 49회 (캐시 읽기): 9만 토큰 × 0.1배 × 49회 = 44.1만 토큰 읽기 비용
• 합계: (11.25 + 44.1) × $3/백만 = 약 $1.66/일
• 절감률: (13.5 - 1.66) / 13.5 = 87.7% 절감

단, 이 절감률은 "입력 대부분이 반복 프리픽스인 워크로드" 조건에서만 나옵니다. 매번 새로운 사용자 쿼리가 프리픽스보다 훨씬 길다면 절감 폭은 줄어들어요.

캐시 적중률은 어떻게 확인하죠?

응답 JSON의 usage 객체를 파싱하면 됩니다.

{
  "usage": {
    "input_tokens": 90000,
    "cache_creation_input_tokens": 90000,
    "cache_read_input_tokens": 0
  }
}

cache_read_input_tokens가 0이면 미적중이에요. 첫 요청이거나, TTL 만료됐거나, 프리픽스가 바뀐 경우죠. 저는 이 필드를 로그에 찍어서 매일 확인합니다.

두 번째 요청부터는 cache_read_input_tokens에 숫자가 들어오기 시작하고, 그만큼 비용이 90% 할인됩니다.

흔한 실수와 해결법

타임스탬프 삽입 함정

시스템 프롬프트에 current_time: 2026-07-06 14:23:05 같은 현재시각을 넣으면 매 초마다 프리픽스가 바뀝니다. 캐시는 바이트 단위로 일치를 확인하기 때문에 1바이트만 달라져도 그 뒤 전부 무효화돼요. 저는 이걸 깨닫기까지 3시간을 날렸습니다.

해결책: 타임스탬프는 user 메시지에만 넣으세요.

JSON 키 순서 비결정성

Python dict를 직렬화하면 키 순서가 실행마다 바뀔 수 있어요. 특히 해시맵 구현에 따라 다릅니다. 이것도 캐시 미적중 원인이 됩니다.

해결책: json.dumps(obj, sort_keys=True) 로 키 순서를 고정하세요.

너무 짧은 프리픽스

2000 토큰짜리 프롬프트를 넣었는데 cache_read_input_tokens가 계속 0이었어요. 모델별 최소 캐시 가능 토큰 수를 확인해보니 이 모델은 4096 토큰 이상이었습니다.

해결책: 공식 문서에서 모델별 최소치를 체크하고, 부족하면 관련 문서를 더 붙여서 프리픽스를 키우세요.

다음 행동

이제 여러분 코드에 적용할 차례입니다. API 호출 로그를 열어서 반복 패턴을 찾아보세요. 시스템 프롬프트가 5천 토큰 이상이고 하루 10회 이상 호출한다면 캐싱으로 바로 효과를 볼 수 있습니다.

손익분기점은 5분 TTL 기준 동일 프리픽스 2회부터예요. 첫 쓰기가 1.25배 비용이지만, 두 번째 읽기가 0.1배라서 합쳐도 1.35배로 무캐시 2회(2배)보다 저렴합니다.

자주 묻는 질문

Q. 1시간 TTL로 늘리면 비용이 더 줄어드나요? A. 쓰기 비용이 기본 입력 단가의 2배로 올라갑니다 (5분 TTL은 1.25배). 하루 호출 빈도가 낮다면 5분 TTL이 더 유리할 수 있어요. 호출 간격이 5분 이내로 빈번하다면 1시간 TTL을 고려하세요.

Q. 브레이크포인트를 4개 모두 써야 하나요? A. 아닙니다. 반복 패턴이 여러 단계에 걸쳐 있을 때만 유용해요. 제 경우 시스템 프롬프트 1개 + tools 정의 1개, 총 2개만 썼습니다.

Q. 다른 LLM 제공사도 비슷한 기능이 있나요? A. 2026년 상반기 기준 OpenAI는 유사 기능을 베타 테스트 중이고, Google Gemini는 컨텍스트 캐싱 API를 제공합니다 (출처: 2026년 상반기 LLM API 가격 비교). 각 제공사 공식 문서에서 최신 정보를 확인하세요.

Q. 캐시가 언제 자동 삭제되나요? A. TTL 만료 시점입니다. 5분 TTL이면 마지막 히트로부터 5분 후, 1시간 TTL이면 1시간 후 삭제돼요. 그 전에 다시 호출하면 TTL이 리셋됩니다.