핵심 요약
- 5분 캐시 쓰기는 기본 입력의 1.25배, 읽기는 대부분 모델에서 0.1배입니다.
- 10,000토큰 접두부를 10번 호출하면 5분 캐시는 캐시 없음의 약 21.5%입니다.
- 최소 길이 미달 시 오류 없이 캐시가 안 걸리니 usage 필드를 확인하세요.
프롬프트 캐싱은 반복되는 앞부분만 싸게 읽는 기능입니다. 요청마다 같은 프롬프트 접두부를 보낸다면 cache_control을 한 줄 추가하는 것만으로 입력 비용을 크게 줄일 수 있습니다. Anthropic 가격 문서에 따르면 5분 캐시 쓰기는 기본 입력 단가의 1.25배입니다. 캐시 읽기(적중)는 대부분의 모델에서 0.1배입니다. 같은 문서에는 5분 캐시는 읽기 1회만 해도, 1시간 캐시는 읽기 2회 뒤에 본전이라고 나와 있습니다.
아래 수치는 제가 API를 호출해 측정한 값이 아닙니다. 공식 단가로 계산한 시뮬레이션입니다.
캐시가 청구되는 구조
프롬프트 캐싱 문서에 따르면 캐시는 tools, system, messages 순서로 이어지는 접두부를 대상으로 합니다. 범위는 cache_control을 지정한 블록까지 포함됩니다. 응답의 usage에는 토큰이 세 갈래로 나뉘어 나옵니다.
cache_creation_input_tokens: 이번 요청에서 캐시에 새로 쓴 토큰입니다. 쓰기 단가로 청구됩니다.cache_read_input_tokens: 캐시에서 읽은 토큰입니다. 읽기 단가로 청구됩니다.input_tokens: 마지막 캐시 지점 뒤에 있는 일반 입력 토큰입니다.
첫 호출은 creation만 찍히고, 이후 호출에서 read가 찍히면 적중한 것입니다.
TTL에 따른 비용 비교
기본 TTL은 5분입니다. 문서에 따르면 1시간 TTL을 쓰려면 ttl을 명시합니다. 이때 쓰기 단가는 기본 입력의 2배입니다.
{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }
가격 문서의 Claude Sonnet 4 단가로 계산해 보겠습니다. 기본 입력은 $3/MTok, 5분 쓰기는 $3.75, 1시간 쓰기는 $6, 읽기는 $0.30입니다. 공통 접두부 10,000토큰을 10번 호출한다고 가정하고, 모든 호출이 TTL 안에 들어온다고 보면 다음과 같습니다.
| 방식 | 계산 | 접두부 비용 |
|---|---|---|
| 캐시 없음 | 100,000토큰 × $3 | $0.30 |
| 5분 캐시 | 쓰기 1회 $0.0375 + 읽기 9회 $0.027 | $0.0645 |
| 1시간 캐시 | 쓰기 1회 $0.06 + 읽기 9회 $0.027 | $0.087 |
이 가정에서는 5분 캐시가 캐시 없음의 약 21.5% 수준입니다. 1시간 캐시는 쓰기가 비싸서 5분 캐시보다 $0.0225 더 듭니다. 그 대신 호출 간격이 5분을 넘어도 읽기 단가를 유지할 수 있습니다.
적중 조건
적중하려면 접두부가 요청 간에 완전히 같아야 합니다. 캐시가 접두부 단위이므로, 변하는 내용(사용자 질문, 타임스탬프 등)은 cache_control 지점 뒤에 둬야 합니다. 시스템 프롬프트 앞쪽에 날짜나 요청 ID를 넣으면 그 뒤가 전부 달라져 미스가 납니다. 이는 접두부 구조에서 따라오는 설계상 결론입니다.
TTL 안에 다음 요청이 들어와야 한다는 조건도 있습니다. 문서에 따르면 캐시 항목의 최소 수명은 5분(기본) 또는 1시간(확장)이고, 이후에 삭제됩니다. 가격 문서에는 적중 시 캐시가 갱신된다고 나옵니다. 5분보다 촘촘히 호출이 오는 서비스는 기본 TTL로 충분합니다.
실패 조건
가장 흔한 실패는 최소 길이 미달입니다. 문서에 따르면 최소 캐시 길이는 모델마다 다릅니다.
| 모델 | 최소 캐시 길이 |
|---|---|
| Opus 4.1, Opus 4, Sonnet 4.5, Sonnet 4 | 1024토큰 |
| Haiku 3.5, Haiku 3 | 2048토큰 |
| Haiku 4.5 | 4096토큰 |
모델을 Sonnet에서 Haiku 4.5로 바꾸면서 같은 프롬프트를 쓰면, 길이가 모자라 캐시가 조용히 안 걸릴 수 있습니다. 이때는 오류가 나지 않고 cache_creation_input_tokens와 cache_read_input_tokens가 모두 0으로 나옵니다. 비용이 줄지 않았다면 이 두 필드부터 확인하세요.
그 밖의 실패 원인은 다음과 같습니다.
- 접두부 앞쪽이 달라지는 경우입니다. 위에서 설명한 구조 때문입니다.
- 호출 간격이 TTL을 넘는 경우입니다.
- 모델을 바꾼 경우입니다. 최소 길이와 단가가 모델마다 다릅니다.
실천 가이드
cache_control 위치와 TTL은 아래 순서로 정하면 됩니다.
- 프롬프트를 정적 부분(도구 정의, 시스템 지시, 고정 문서)과 동적 부분(사용자 입력)으로 나눕니다. 정적 부분을 앞에 두고, 그 마지막 블록에
cache_control을 붙입니다. - 사용 모델의 최소 캐시 길이를 넘는지 확인합니다.
- 호출 간격이 5분 안쪽이면 기본 TTL을 씁니다. 간격이 불규칙하고 5분을 자주 넘으면 1시간 TTL을 고려합니다. 1시간 캐시는 읽기가 2회 이상 발생해야 손익이 맞습니다.
- 배포 후
usage의cache_read_input_tokens비율을 로그로 남깁니다. 두 번째 호출부터 이 값이 0이면 접두부가 달라지고 있는 것입니다.
모델별 단가와 TTL 정책은 바뀔 수 있습니다. 적용하기 전에 가격 문서로 현재 값을 확인하세요.
자주 묻는 질문
Q. 프롬프트 캐싱을 쓰면 비용이 얼마나 줄어드나요?
본문의 시뮬레이션은 Sonnet 4 공식 단가로 계산한 값입니다. 10,000토큰 접두부를 10번 호출하면 5분 캐시는 $0.0645로 캐시 없음($0.30)의 약 21.5% 수준입니다. 실제 API 호출로 측정한 값은 아닙니다.
Q. 5분 TTL과 1시간 TTL 중 무엇을 골라야 하나요?
호출 간격이 5분 안쪽이면 기본 TTL로 충분합니다. 간격이 불규칙하고 5분을 자주 넘으면 1시간 TTL을 고려하세요. 1시간 캐시는 쓰기 단가가 기본 입력의 2배라 읽기가 2회 이상 발생해야 손익이 맞습니다.
Q. 캐시가 적용되는지 어떻게 확인하나요?
응답 usage의 cache_creation_input_tokens와 cache_read_input_tokens를 보세요. 첫 호출에는 creation만 찍히고, 이후 호출에서 read가 찍히면 적중한 것입니다. 두 값이 모두 0이면 최소 캐시 길이 미달일 수 있습니다.
참고 자료
이 글은 웹 검색으로 확인한 위 출처를 바탕으로 AI(claude-sonnet-5-5)가 작성했습니다. 수치·가격은 출처 원문에서 다시 확인하세요.