Claude 프롬프트 캐싱 비용: 실제로 싸지는 조건 4가지

프롬프트 캐싱은 요청에 cache_control 한 줄만 붙이면 끝나는 것처럼 보입니다. 그런데 캐시할 앞부분이 모델별 최소 길이보다 짧으면, 오류 하나 없이 그냥 정가로 처리돼요. 코드는 성공하고 청구서만 그대로인 거죠.

가격표를 놓고 보면 캐싱은 할인이라기보다 선불에 가깝습니다. 캐시에 쓸 때 기본 입력의 1.25배(5분) 또는 2배(1시간)를 먼저 내고, 다시 읽을 때 대부분 0.1배로 갚는 구조거든요.

그래서 저는 캐싱을 켜기 전에 같은 앞부분을 몇 번 다시 보낼지부터 세어 보길 권합니다. 켠 뒤에는 매번 같은 앞부분의 끝에 cache_control이 걸려 있는지, 응답 usage의 cache_read_input_tokens가 0보다 큰지 확인하세요.

2026년 9월 18일 Anthropic 공식 프롬프트 캐싱·가격 문서 기준이고, 모델별 최소 길이와 적중 단가 예외는 10월 14일에 다시 확인했습니다. 금액 대신 기본 입력 단가에 대한 배수로 적었습니다. 모델별 금액은 Claude 공식 가격 페이지에 있습니다.

몇 번 읽어야 본전인가

5분 캐시는 한 번, 1시간 캐시는 두 번 다시 읽으면 본전입니다. 같은 앞부분을 한 번 쓰고 열 번 읽으면, 캐시 없이 열한 번 보낼 때 기본 입력의 11배이던 비용이 5분 캐시로는 2.25배가 돼요. 1.25 + 0.1 × 10 = 2.25라서 그 부분 입력 비용이 약 5분의 1로 줄어듭니다.

캐시	쓰기	적중	본전
5분	기본 입력의 1.25배	0.1배	적중 1회
1시간	기본 입력의 2배	0.1배	적중 2회

적중 단가는 모델에 따라 더 낮습니다. 10월 14일 기준 Fable 5.1은 0.025배, Opus 5.5와 Sonnet 5.5는 0.05배이고 나머지는 0.1배예요. Sonnet 5.5는 10월 7일에 0.1배에서 0.05배로 내려갔습니다. 이런 모델에서는 적중할 때 아끼는 폭이 더 큽니다.

그렇다고 모든 요청에 캐시를 켜 두는 건 답이 아닙니다. 한 번 쓰고 한 번도 못 읽으면 그 부분에 25%를 더 낸 것이 되거든요. 한 번 보내고 마는 요청, 매번 내용이 달라지는 요청에는 손해입니다.

최소 길이에 못 미치면 조용히 정가

도입에서 말한 그 함정입니다. 캐시할 앞부분이 최소 길이에 못 미치면 cache_control을 붙여도 오류 없이 캐싱만 건너뜁니다.

2026년 10월 14일 문서 기준 주요 모델의 최소 길이입니다(Claude API·Claude Platform on AWS·Google Cloud·Microsoft Foundry 공통).

최소 길이	모델
512 토큰	Fable 5.1, Opus 5.5, Sonnet 5.5, Haiku 5.5, Opus 5
1,024 토큰	Sonnet 5, Opus 4.8, Sonnet 4.6
2,048 토큰	Opus 4.7
4,096 토큰	Haiku 4.5, Opus 4.6

표를 보면 최신 모델이라고 늘 더 낮지는 않습니다. 모델을 바꿀 때 이 값을 다시 보지 않는 것이 흔한 실수이고, 예전 모델에서 1,024 토큰에 맞춘 앞부분이 새 모델에서 통과한다는 보장은 없어요.

최소값에 조금 못 미치면 캐시할 내용을 늘려 문턱을 넘기는 편이 나을 때가 많습니다. Amazon Bedrock은 최소값과 동작이 따로 정해져 있으니 Bedrock 문서를 보세요.

5분은 요청이 시작될 때부터

5분 수명은 응답이 끝날 때가 아니라 요청이 시작될 때부터 셉니다. 응답이 4분 동안 스트리밍됐다면, 다음 요청은 그 응답이 끝난 뒤 약 1분 안에 시작해야 같은 앞부분을 읽어요. 응답 생성 시간도 수명을 깎는 셈입니다.

대신 적중할 때마다 수명이 추가 비용 없이 갱신됩니다. 5분 안에 한 번씩 계속 쓰는 워크로드라면 한 번 쓰고 오래 버팁니다.

긴 응답을 만드는 에이전트나, 사람이 결과를 읽고 다음 지시를 입력하는 대화형 작업은 생각보다 자주 5분을 넘깁니다. 그때 쓰는 게 1시간 캐시("ttl": "1h")인데, 쓰기가 2배라 적중 두 번을 확보할 수 있을 때만 이득이에요.

중단점은 매번 같은 마지막 블록에

캐시는 tools → system → messages 순서로, 요청 맨 앞부터 중단점을 건 블록까지 통째로 해시합니다. 그래서 중단점 안쪽에 매번 바뀌는 값이 하나라도 있으면 해시가 달라져 다음 요청이 적중하지 못해요.

같은 이유로 세 층 중 어느 층이 바뀌면 그 층과 그 뒤 층이 모두 무효가 됩니다. 웹 검색이나 인용 기능을 켜고 끄는 것도 시스템 프롬프트를 바꾸니 여기에 해당합니다.

캐시할 수 있는 대상은 도구 정의(tools), 시스템 블록, 사용자·어시스턴트 메시지의 텍스트, 사용자 턴의 이미지와 문서, 도구 호출과 결과 블록입니다.

정적인 앞부분과 매번 바뀌는 꼬리로 된 프롬프트라면, 앞부분의 마지막 블록에 cache_control을 겁니다. 공식 문서의 예시를 줄인 형태입니다.

{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "system": [{
    "type": "text",
    "text": "<매번 같은 긴 지시문·참고 문서>",
    "cache_control": { "type": "ephemeral" }
  }],
  "messages": [{ "role": "user", "content": "<이번 질문>" }]
}

타임스탬프·요청 ID·사용자 입력이 중단점 안쪽에 하나라도 들어가면 매 요청이 1.25배 쓰기가 됩니다. 바뀌는 값은 중단점 뒤로 보내세요.

긴 대화와 20블록 되돌아보기

긴 대화는 20블록 안에 중단점이 하나 더 있어야 캐시가 이어집니다. 캐시 쓰기는 중단점에서만 일어나고, 읽기는 중단점에서 한 블록씩 거슬러 가며 이전 요청이 써 둔 항목을 찾는데 최대 20개 위치까지만 보거든요. 대화가 한 번에 많이 늘면 이전 항목을 놓칩니다.

1. 10블록짜리 첫 턴이 10번 위치에 캐시를 씁니다.
2. 15블록이 된 둘째 턴은 15번에서 10번까지 거슬러 가 적중합니다.
3. 35블록이 된 셋째 턴은 35번부터 16번까지 20개만 보고 멈춰, 15번 항목을 한 칸 차이로 놓칩니다.

해결은 중단점을 하나 더 두는 것입니다. 그 자리에서 새 되돌아보기 창이 시작돼요. 중단점은 요청당 최대 4개까지 쓸 수 있습니다.

여기에 자동 캐싱까지 더하면 400 오류가 나니 주의하세요. 자동 캐싱은 중단점 4자리 중 하나를 차지해서, 명시적 중단점 4개가 이미 있으면 들어갈 자리가 없습니다.

캐시가 돌았는지 확인하는 법

확인할 곳은 usage의 두 필드뿐입니다. 같은 앞부분으로 요청을 두 번 연속 보내고 두 번째 응답의 usage를 보세요.

cache_read_input_tokens가 0보다 크면 성공입니다. 10월 14일 테스트 환경(Windows 11 · Windows PowerShell 5.1, Claude Code 2.1.296)에서 claude -p "Reply with exactly: ok" --model haiku --output-format json을 빈 폴더에서 두 번 연달아 실행하고(haiku는 Claude Code에서 Haiku 5.5로 잡힙니다) usage만 뽑았습니다. Claude Code는 매 호출에 같은 도구 정의와 시스템 프롬프트를 앞에 붙이니, 같은 앞부분을 두 번 보낸 셈입니다.

필드	첫 호출	두 번째 호출
input_tokens	2	2
cache_creation_input_tokens	9,814	0
cache_read_input_tokens	16,422	26,236
output_tokens	4	4

첫 호출이 쓴 9,814토큰을 두 번째 호출이 그대로 읽어서, 읽기가 16,422 + 9,814 = 26,236이 됐습니다. 쓰기는 0이에요. 첫 호출에도 읽기가 있는 건 앞부분의 앞쪽 일부가 이미 캐시에 있었다는 뜻이고, 중단점이 여러 개면 이렇게 한 응답에 쓰기와 읽기가 함께 찍힙니다.

보이는 값	뜻	할 일
두 캐시 필드 모두 0	캐싱 안 됨	최소 길이 확인
매번 쓰기만 크고 읽기 0	중단점 앞이 매번 바뀜	중단점 옮기기
읽기가 크고 쓰기가 작음	정상 동작	그대로

병렬로 보낸 요청이 모두 캐시를 새로 쓴다면 이유가 따로 있습니다. 캐시 항목은 첫 응답이 시작된 뒤에야 쓸 수 있어서, 같은 앞부분을 동시에 던지면 서로의 캐시를 보지 못해요. 첫 응답이 시작될 때까지 기다린 뒤 나머지를 보내세요.

다른 사람들이 겪은 문제

이 필드를 보지 않으면 실패가 몇 달씩 지나갑니다. 아래 공개 사례들이 모두 그랬어요.

• storybite(2026-02-21, anthropic-sdk-python #1194): 문서의 1,024 토큰과 달리 2,048 토큰을 넘어야 캐시가 걸리는 것 같다고 보고했습니다. 2026-08-05에 저장소 기여자가 SDK가 아니라 API 쪽 문제였고 지금은 재현되지 않으며 1,060 토큰 수준도 문서대로 캐시된다고 답하고 닫았습니다.
• willsf1862(2026-06-29, VS Code #323642): 대화가 길어져 중단점을 다시 배치할 때 중단점 앞 내용도 함께 바뀌어 전체 쓰기가 반복된다고 보고했습니다. 연속 요청 155건 중 약 8.4%가 전체 쓰기였습니다.
• thebeals(2026-09-04, Claude Code #91971): 세션을 이어 가는 호출에서 고정 앞부분은 적중하는데, 턴마다 늘어난 내용은 다음 호출에서 읽히지 않는다고 보고했습니다. 원인은 확정되지 않았습니다.
• kennethsinder(2026-09-03, harn #7940): 자기 코드의 중단점이 실제로 캐시를 데우는지 확인할 방법이 없다고 문제를 제기했습니다. 확인된 결함이 아니라 검증 공백이라고 적었습니다.

공통점은 오류가 나지 않는다는 데 있습니다. 캐싱이 깨져도 응답은 멀쩡히 오니까, usage를 직접 들여다보지 않으면 알 길이 없어요.

마치며

프롬프트 캐싱에서 제일 조심할 건 실패가 조용하다는 점입니다. 최소 길이에 못 미쳐도 오류 없이 정가가 되고, 중단점 안쪽에 타임스탬프가 끼어 있으면 요청마다 1.25배 쓰기만 반복됩니다. 선불로 낸 쓰기 비용을 적중으로 갚아야 이득이니, 켜기 전에 몇 번 다시 읽을지 세어 보고, 켠 뒤에는 결과를 숫자로 확인하는 게 맞다고 봅니다.

지금 캐싱을 쓰고 있다면 같은 요청을 두 번 보내 두 번째 응답의 cache_read_input_tokens부터 확인해 보세요. Claude Code에서 캐시가 비용을 어떻게 가르는지는 토큰 절약 8가지를 직접 잰 글에 실제 숫자로 있습니다.