Claude 프롬프트 캐싱에는 아주 멋진 숫자 하나와 밟기 쉬운 함정 하나가 있다. 캐시 읽기는 일반 입력 비용의 0.1×밖에 안 들지만, 캐시 쓰기는 일반 입력보다 비싸다. Anthropic의 현재 문서에 따르면 활성 Claude 모델 기준으로 5분 캐시 쓰기는 입력 가격의 1.25×, 1시간 쓰기는 2×, 캐시 히트는 0.1×다 (Anthropic prompt caching docs).
그러니 캐싱은 단순한 지연시간 기능이 아니라 가격 기능이다. 앱이 긴 시스템 프롬프트, 도구 스키마, 예시 묶음, 정책 번들, 검색해온 문서, 멀티턴 상태를 반복해서 쓴다면, 출력 토큰을 측정하듯 캐시 쓰기와 읽기도 측정해야 한다.
오늘, 2026년 6월 14일 기준으로 한 가지 변수가 있다. Anthropic은 6월 9일 Claude Fable 5를 출시했고, 6월 12일에는 Fable 5와 Mythos 5 접근을 복구하는 동안 일시 중단한다고 업데이트를 올렸다 (Anthropic). OneHop도 anthropic/claude-fable-5를 프롬프트 캐시 지원 모델로 올려두었지만, 현재 모델 페이지에서는 일시적으로 사용할 수 없다고 표시한다 (OneHop). 지금 통합은 만들어두고, 모델 id는 설정 가능하게 두고, 접근이 열리면 켜라.
개발자에게 실제로 필요한 캐시 계산
Anthropic의 프롬프트 캐시는 프롬프트 접두부를 저장한다. 재사용되는 부분은 완전히 같아야 한다. 도구, 시스템 콘텐츠, 메시지가 이 순서로 고려되며, 캐시는 cache_control로 표시한 블록까지 적용된다 (Anthropic prompt caching docs).
쓸모 있는 가격 모델은 단순하다. 재사용 가능한 접두부가 입력 토큰 100,000개라고 해보자.
| 캐시 모드 | 쓰기 비용 배수 | 읽기 비용 배수 | 손익분기 직감 |
|---|---|---|---|
| 캐시 없음 | 요청마다 1.0× | 없음 | 매번 입력 비용 전액 지불 |
| 5분 캐시 | 한 번 1.25× | 히트마다 0.1× | 첫 재사용부터 이득 |
| 1시간 캐시 | 한 번 2.0× | 히트마다 0.1× | 더 많은 재사용 또는 더 긴 유휴 간격이 필요 |
Claude Fable 5의 경우 Anthropic은 출시 글에서 입력 토큰 100만 개당 $10, 출력 토큰 100만 개당 $50를 제시했고, 프롬프트 캐싱 문서에서는 Fable 5 캐시 가격을 5분 쓰기 $12.50/M, 1시간 쓰기 $20/M, 캐시 히트 $1/M로 적고 있다 (Anthropic, prompt caching docs).
Anthropic 정가 기준으로 보면, 그 100k 토큰 접두부 비용은 이렇다.
- 일반 입력:
$1.00 - 5분 쓰기:
$1.25 - 1시간 쓰기:
$2.00 - 캐시 읽기:
$0.10
따라서 같은 100k 토큰 접두부를 TTL 안에서 두 번 사용하면, 5분 캐싱 비용은 $1.25 + $0.10 = $1.35다. 캐싱이 없으면 $2.00다. 1시간 캐시는 두 번 사용 시 $2.10이라 두 호출에서는 손해지만, 세 번째 호출이 있거나 더 긴 중단 뒤 차가운 재쓰기를 피하면 이긴다.
내가 프로덕션에서 쓰는 규칙은 이렇다. 뜨거운 루프에는 기본 5분. 사람이 멈춰 읽거나, 에이전트가 도구를 기다리거나, 워크플로가 몇 분 뒤 재개되는 경우에는 1시간.
캐싱을 켜는 두 가지 방법
Anthropic은 이제 두 접근법을 문서화한다. 가장 빠른 길은 자동 캐싱이다. 최상위 cache_control 필드를 추가하면 Claude가 대화가 길어질수록 중단점을 앞으로 옮긴다. 더 통제된 길은 명시적 중단점이다. 안정적인 접두부의 마지막 콘텐츠 블록에 cache_control을 넣는다 (Anthropic prompt caching docs).
자동 캐싱은 채팅 기록과 에이전트 상태에 좋다.
import os
from anthropic import Anthropic
client = Anthropic(
api_key=os.environ["ONEHOP_API_KEY"],
base_url=os.getenv("ANTHROPIC_BASE_URL", "https://api.onehop.ai/v1"),
)
message = client.messages.create(
model=os.getenv("CLAUDE_MODEL", "anthropic/claude-fable-5"),
max_tokens=700,
cache_control={"type": "ephemeral"},
system="You are a senior backend engineer. Be concise and specific.",
messages=[
{"role": "user", "content": "My app uses FastAPI, Postgres, and Redis."},
{"role": "assistant", "content": "Got it. What do you want to change?"},
{"role": "user", "content": "Design a cache key strategy for user dashboards."},
],
)
print(message.content[0].text)
print(message.usage.model_dump())이게 OneHop 전환 경로다. Anthropic 스타일 요청은 유지하고, base URL을 설정 가능하게 만든 뒤, https://api.onehop.ai/v1를 가리키게 하면 된다. OneHop 모델 페이지도 모델 id를 anthropic/claude-fable-5로 보여주며, 신규 사용자에게 카드 없이 $10 무료 크레딧을 준다고 안내한다 (OneHop). 빠른 길을 원한다면 Claude Fable 5 on OneHop을 열고 $10 무료로 시작하면 된다.
명시적 캐싱은 접두부는 안정적이지만 사용자 메시지가 요청마다 바뀔 때 더 낫다. 바뀌는 부분 앞에 중단점을 둬라.
from anthropic import Anthropic
import os
client = Anthropic(
api_key=os.environ["ONEHOP_API_KEY"],
base_url="https://api.onehop.ai/v1",
)
response = client.messages.create(
model="anthropic/claude-fable-5",
max_tokens=500,
system=[
{
"type": "text",
"text": open("system_prompt.md").read(),
"cache_control": {"type": "ephemeral"},
}
],
messages=[
{"role": "user", "content": "Review this migration plan for race conditions."}
],
)
print(response.usage.model_dump())
1시간 TTL을 쓰는 TypeScript 버전
앱에 비싼 정적 컨텍스트가 있고 현실적인 유휴 간격이 있다면 1시간 캐싱을 써라. 예를 들면 CI를 기다리는 코드 리뷰 에이전트, 사람이 잠깐 멈추는 고객지원 코파일럿, 법률 리서치 세션, 도구가 몇 분씩 걸리는 다단계 데이터 분석 같은 것들이다.
Anthropic 문서는 1시간 TTL을 {"type":"ephemeral","ttl":"1h"}로 보여주며, 자동 캐싱은 기본적으로 5분을 사용한다고 말한다 (Anthropic prompt caching docs).
import Anthropic from "@anthropic-ai/sdk";
import fs from "node:fs";
const client = new Anthropic({
apiKey: process.env.ONEHOP_API_KEY!,
baseURL: process.env.ANTHROPIC_BASE_URL ?? "https://api.onehop.ai/v1",
});
const policyPack = fs.readFileSync("policy-pack.md", "utf8");
const msg = await client.messages.create({
model: process.env.CLAUDE_MODEL ?? "anthropic/claude-fable-5",
max_tokens: 800,
system: [
{
type: "text",
text: policyPack,
cache_control: { type: "ephemeral", ttl: "1h" },
},
],
messages: [
{
role: "user",
content: "Apply the policy pack to this refund request: customer used 3 of 10 seats.",
},
],
});
console.log(msg.content);
console.log(msg.usage);중요한 부분은 지루할 정도로 단순하다. 모델과 base URL을 코드 깊숙이 숨기지 마라. 둘 다 환경 변수에 둬라. 지금 Fable 5 가용성은 움직이고 있다. 통합 코드는 비즈니스 로직을 수정하지 않고도 다른 활성 Claude 모델로 fallback할 수 있어야 한다.
사용량에서 무엇을 모니터링할까
프롬프트 캐싱은 사용량 필드를 보기 전까지는 보이지 않는다. Anthropic은 cache_creation_input_tokens, cache_read_input_tokens 같은 필드를 확인해 캐싱 여부를 검증하라고 말한다. 둘 다 0이면 프롬프트가 캐시되지 않은 것이다. 흔한 이유는 모델의 최소 캐시 가능 길이를 넘지 못했기 때문이다 (Anthropic prompt caching docs).
요청마다 이것들을 로그로 남겨라.
const usage = msg.usage;
console.log({
input: usage.input_tokens,
output: usage.output_tokens,
cacheCreate: usage.cache_creation_input_tokens,
cacheRead: usage.cache_read_input_tokens,
});더 최신 사용량 객체의 경우, Anthropic 문서에는 캐시 생성이 ephemeral_5m_input_tokens, ephemeral_1h_input_tokens 같은 TTL별 버킷으로 나뉘어 표시되기도 한다. 처음에는 전체 사용량 객체를 캡처해라. 정확히 어떤 게이트웨이와 SDK 버전을 돌리고 있는지 확인한 뒤 나중에 정규화하면 된다.
좋은 대시보드는 네 가지 질문에 답한다.
- 캐시에 쓰이는 토큰은 몇 개인가?
- 캐시에서 읽히는 토큰은 몇 개인가?
- 라우트별 캐시 읽기/쓰기 비율은 어떤가?
- 어떤 프롬프트가 유휴 간격 뒤 큰 차가운 쓰기를 만드는가?
cache_creation_input_tokens가 높고 cache_read_input_tokens가 거의 0에 머문다면, 중단점이 바뀌는 콘텐츠 뒤에 있을 가능성이 크다. 더 앞으로 옮겨라.
5분이냐 1시간이냐: 사용자 행동으로 고른다
촘촘한 요청 루프에는 5분 캐싱을 써라. 20초마다 도구를 호출하는 코딩 에이전트, 사용자가 빠르게 후속 메시지를 보내는 채팅 앱, 비슷한 분류 작업 묶음은 여기서 시작하는 게 맞다. 쓰기 프리미엄은 1.25×뿐이고, Anthropic 문서에 따르면 읽을 때마다 캐시 수명은 무료로 갱신된다 (Anthropic prompt caching docs).
비싼 접두부가 5분 뒤에도 다시 쓰일 가능성이 높다면 1시간 캐싱을 써라. 사람이 중간에 개입하는 워크플로가 전형적인 사례다. 모델이 외부 시스템에 작업을 보내고, 브라우저를 기다리고, CI를 폴링하거나, 승인을 기다리며 멈추는 장기 실행 에이전트도 마찬가지다.
작은 프롬프트는 캐시하지 마라. Anthropic은 모델과 플랫폼별 최소 캐시 가능 프롬프트 길이를 문서화한다. Fable 5의 경우 Claude API 최소값은 512 토큰으로 표시되어 있고, Bedrock은 일부 모델에서 다른 최소값을 가진다 (Anthropic prompt caching docs). 더 짧은 프롬프트는 그냥 캐싱 없이 처리될 수 있다.
실전 체크리스트는 이렇다.
- 안정적인 콘텐츠를 먼저 둬라: 도구, 시스템 프롬프트, 예시, 참고 문서.
- 바뀌는 데이터는 캐시된 접두부 뒤에 둬라: 타임스탬프, 요청 id, 사용자 텍스트.
- 대화에는 자동 캐싱부터 시작해라.
- 접미부가 호출마다 바뀌면 명시적 중단점으로 전환해라.
- 유휴 간격이 2× 쓰기 비용을 정당화할 때만 1시간 TTL을 써라.
- 성공했다고 말하기 전에 사용량 필드를 로그로 남겨라.
OneHop으로 연결하고, 그다음 측정하라
가장 깔끔한 통합은 엔드포인트 한 줄 변경과 환경 변수 기반 모델 선택이다.
export ONEHOP_API_KEY="..."
export ANTHROPIC_BASE_URL="https://api.onehop.ai/v1"
export CLAUDE_MODEL="anthropic/claude-fable-5"그다음 Anthropic Messages 코드는 유지하고 cache_control만 추가하면 된다.
OneHop의 Fable 5 페이지는 현재 공식 정가보다 낮은 가격, 카드 없는 $10 스타터 크레딧, 그리고 해당 모델용 Anthropic Messages 라우트를 홍보하고 있다 (OneHop). 6월 12일 Anthropic 업데이트 기준으로 Fable 5 접근이 일시 중단되어 있으니, 모델 fallback을 나중에 생각할 일이 아니라 롤아웃의 일부로 넣어라.
보상은 단순하다. 앱이 큰 접두부를 반복한다면, 0.1× 캐시 읽기는 프롬프트 엔지니어링을 비용 엔지니어링으로 바꾼다. 5분 캐싱부터 시작해라. 로그에서 중단 뒤 차가운 재쓰기가 보이는 워크플로만 1시간 캐싱으로 옮겨라. Claude Fable 5의 가용성이 돌아왔을 때 빠른 길을 원한다면 Claude Fable 5 on OneHop을 써보고 $10 무료로 시작하면 된다.
