Prompt Caching 완전 가이드 — Claude API 비용 90% 절감과 5분·1시간 TTL 활용법
Claude API를 운영 환경에서 쓰다 보면 시스템 프롬프트·문서·도구 정의처럼 매번 반복되는 입력이 전체 토큰 비용의 절반 이상을 차지하는 경우가 많다. Anthropic이 제공하는 Prompt Caching은 이런 반복 입력을 캐시에 저장하고, 같은 캐시를 읽을 때 입력 단가를 10%만 청구해 최대 90%의 비용 절감을 가능하게 한다.
이 글은 Prompt Caching의 작동 원리, 2026년 변경된 5분·1시간 TTL 구조, cache_control 설정 방법, 실전 비용 시뮬, 그리고 캐시가 깨지는 흔한 함정을 한 번에 정리한다. 시스템 프롬프트·RAG 문서·Tool 정의를 반복해 쓰는 워크플로우라면 적용 즉시 단가가 떨어진다.
01 Prompt Caching이란 — 한 줄 정리
Anthropic API가 제공하는 캐싱 기능으로, 반복되는 프롬프트 접두부(prefix) 를 서버 측에 저장해 두고, 같은 접두부를 재사용할 때 입력 토큰 단가를 0.1배로 청구하는 메커니즘이다.
캐시 적중 비용 = 기본 입력 단가 × 0.1 (90% 할인)
Cache Write
기본 단가 × 1.25 (5분)
또는 × 2.0 (1시간)
Cache Read
기본 단가 × 0.1
(90% 할인 적용)
손익분기점
5분 캐시 1회 적중
1시간 캐시 2회 적중
💡 핵심 — 반복 사용이 전제
캐시 작성(Write)은 기본 단가보다 비싸므로, 같은 캐시를 한 번도 재사용하지 않으면 오히려 손해다. 5분 TTL은 단 1회 적중만 해도 흑자, 1시간 TTL은 2회 적중부터 흑자.
02 2026년 TTL 변경 — 60분 → 5분 기본·1시간 옵션
2026년 초 Anthropic이 기본 캐시 TTL을 60분에서 5분으로 단축하면서 많은 프로덕션 워크플로우에서 실효 API 비용이 30～60% 증가하는 사건이 있었다. 5분 안에 같은 캐시를 재사용하지 못하면 캐시가 만료되고, 다시 작성 비용을 부담해야 한다.
| 항목 | 5분 TTL (기본) | 1시간 TTL (옵션) |
|---|---|---|
| 캐시 유효 기간 | 5분 (300초) | 60분 (3,600초) |
| Write 단가 배율 | 1.25배 | 2.0배 |
| Read 단가 배율 | 0.1배 | 0.1배 |
| 손익분기점 | 1회 재사용 | 2회 재사용 |
| 권장 워크플로우 | 짧은 챗봇 세션·짧은 인터랙션 | 긴 분석·문서 RAG·코드 작업 |
03 cache_control 설정 코드
캐시는 메시지 content 블록에 cache_control: { type: "ephemeral" } 필드를 추가해 활성화한다. 시스템 프롬프트·문서·Tool 정의 중 캐싱하려는 블록에 표시한다.
# Python SDK 예시
import anthropic
client = anthropic.Anthropic()
message = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
system=[
{
"type": "text",
"text": "You are a helpful assistant."
},
{
"type": "text",
"text": "[긴 시스템 프롬프트/문서 1만 토큰...]",
"cache_control": {"type": "ephemeral"} # 5분 캐시
}
],
messages=[
{"role": "user", "content": "질문 내용..."}
]
)
# 1시간 캐시 (베타) — ttl 필드 추가
"cache_control": {"type": "ephemeral", "ttl": "1h"}
📌 캐시 최소 길이 제한
캐시할 콘텐츠는 모델별 최소 토큰 수 이상이어야 한다. Sonnet·Opus는 1,024 토큰 이상, Haiku는 2,048 토큰 이상이 권장 임계. 너무 짧은 프롬프트는 캐시 효과가 없거나 거절된다.
04 비용 시뮬 — 1만 토큰 시스템 프롬프트 100회 호출
긴 시스템 프롬프트(1만 토큰)를 가진 챗봇이 1시간 동안 100회 응답한다고 가정. Sonnet 4.6 입력 단가 $3 / 1M tokens 기준 비용을 비교하면 차이가 극명하다.
1시간 100회 호출 시 비용 비교 (USD)
캐시 X 5분 캐시 1시간 캐시 $3.00 $0.40 $0.32캐시 X : 1만 × 100 × $3 / 1M = $3.00
5분 캐시 : Write 1회($3 × 1.25 / 100 = $0.0375) + Read 99회($3 × 0.1 × 99 / 100 = $0.297) ≈ $0.33 (재계산 시 $0.34 안팎)
1시간 캐시 : Write 1회($3 × 2.0 / 100 = $0.06) + Read 99회($0.297) ≈ $0.36
※ 실제 적중 패턴·5분 만료에 따라 변동, 짧은 인터벌 호출에서 5분 캐시가 더 효율적
캐시 적중률 90%만 유지해도
API 비용이 약 1/10 수준으로 떨어진다.
시스템 프롬프트·RAG 문서·Tool 정의가 반복되는 모든 워크플로우의 첫 최적화 대상이다.
05 캐시가 깨지는 함정 5가지
캐시는 접두부가 100% 동일해야 적중한다. 한 글자라도 다르면 새 캐시 작성이 발생해 비용이 다시 든다. 가장 흔한 함정 5가지.
① 동적 타임스탬프 삽입
시스템 프롬프트에 "현재 시각: 2026-05-21 14:35:22" 같은 동적 값이 들어가면 매번 새 캐시. 시간은 사용자 메시지 쪽으로 분리.
② 사용자 정보 접두부 혼합
시스템 프롬프트 안에 "사용자명: 김철수" 같이 사용자별 다른 값이 들어가면 캐시가 사용자 수만큼 분리됨.
③ Tool 정의 순서 변경
Tools 배열의 순서가 바뀌면 캐시 무효. Tool 추가·삭제·재정렬 시 신규 캐시 작성.
④ 모델 변경
Sonnet에서 Opus로 변경하면 캐시 무효. 같은 캐시는 동일 모델 내에서만 공유.
⑤ 5분 미접속
5분 동안 같은 캐시를 한 번도 안 쓰면 자동 만료. 트래픽이 들쭉날쭉한 워크플로우는 1시간 TTL 또는 워밍업 호출 활용.
06 실전 활용 패턴 4가지
| 패턴 | 캐싱 대상 | TTL 추천 |
|---|---|---|
| 챗봇·고객 지원 | 시스템 프롬프트 + FAQ 문서 | 5분 (활성 트래픽) |
| RAG 응답 | 검색된 문서 청크 (자주 반복되는 것) | 1시간 (분석 세션) |
| 코드베이스 분석 | 프로젝트 구조 + 핵심 파일 | 1시간 (긴 작업) |
| Tool 사용 에이전트 | Tools 정의 + 시스템 프롬프트 | 5분 또는 1시간 |
📊 응답 메타데이터에서 적중률 확인
API 응답 객체의 usage.cache_creation_input_tokens 와 usage.cache_read_input_tokens 필드로 캐시 작성·적중 토큰을 추적할 수 있다. 운영 대시보드에 적중률 지표로 모니터링.
07 Q&A 자주 묻는 질문 5가지
Q캐시는 다른 사용자와 공유되나요?
A같은 조직(workspace) 내에서는 공유 가능하지만, 외부 조직과는 격리된다. 캐시 키는 콘텐츠 해시 + API 키 조직 ID 기반이라 다른 회사 데이터가 섞이지 않는다.
Qcache_control을 여러 블록에 동시 사용할 수 있나요?
A최대 4개 캐시 브레이크포인트까지 동시 지정 가능. 시스템 프롬프트 1개 + 문서 2개 + Tools 1개 식으로 나눠 캐싱 가능하다. 다만 각 브레이크포인트는 모두 최소 토큰 임계를 충족해야 한다.
Q짧은 프롬프트에도 캐시가 적용되나요?
A최소 임계 미만의 짧은 프롬프트는 cache_control을 지정해도 무시되거나 거절된다. Sonnet·Opus는 1,024 토큰 이상, Haiku는 2,048 토큰 이상이 권장 임계. 500 토큰 짜리 시스템 프롬프트는 캐시 의미가 없다.
Q캐시는 AWS Bedrock·GCP Vertex에서도 작동하나요?
A그렇다. AWS Bedrock·GCP Vertex AI 채널에서도 Claude 모델 호출 시 prompt caching이 지원된다. 다만 가격·TTL 정책은 클라우드별로 약간 다를 수 있어 공식 문서 확인 필요.
QClaude Code 같은 CLI 도구도 자동으로 prompt caching을 쓰나요?
AClaude Code는 내부적으로 시스템 프롬프트·CLAUDE.md·도구 정의에 caching을 자동 적용한다. 사용자가 직접 설정하지 않아도 같은 세션에서 반복 호출이 빠르고 저렴한 이유다.
결론 — 적용 우선순위
Prompt Caching은 별도 코드 변경 거의 없이 비용을 1/5～1/10로 줄일 수 있는 가장 가성비 좋은 최적화다.
지금 당장 — 시스템 프롬프트가 1,024 토큰 이상이고 같은 세션에서 반복 호출이 있다면 cache_control: {type: "ephemeral"} 한 줄 추가. 5분 TTL로 시작.
다음 주 — 캐시 적중률을 응답 메타데이터로 모니터링. 80% 이상 적중하면 비용 절감 효과 가시화.
한 달 후 — 트래픽이 1시간 단위로 묶이는 분석·코딩 워크플로우는 ttl: "1h" 옵션으로 확장. 5분 TTL 만료를 회피.
✅ Prompt Caching 적용 체크리스트
본 글은 정보 정리·교육 목적이며 Anthropic의 공식 가이드를 갈음하지 않는다. Prompt Caching 가격·TTL 정책은 수시 변경되므로 적용 직전 platform.claude.com/docs/en/build-with-claude/prompt-caching 공식 문서를 확인해야 한다.
#PromptCaching #ClaudeAPI #Anthropic #cache_control #ephemeral #TTL5min #TTL1hour #API비용절감 #Sonnet4.6 #Opus4.7 #Haiku4.5 #LLM최적화 #시스템프롬프트 #RAG #API토큰비용
댓글