프롬프트 캐싱 사용법과 과금

1折AI에서 Claude 프롬프트 캐싱 사용법: 활성화 방법, 최소 길이, 히트 확인 방법, 히트 과금 방식, Claude Code의 캐싱 동작.

프롬프트 캐싱을 사용하면 반복해서 보내는 긴 접두사(시스템 프롬프트, 도구 정의, 긴 문서, 대화 기록)를 처음 한 번은 쓰기로, 이후에는 읽기로 과금합니다. 이 사이트에서는 캐시 읽기와 캐시 쓰기가 공식 정가 기준으로 과금되며, 입력/출력 할인이 적용되지 않습니다. 모델별 캐시 단가는 모델 및 가격에서 확인할 수 있습니다.

결론부터

Claude Code는 기본적으로 캐싱이 활성화되어 있습니다. 연결하는 즉시 적용됩니다.
직접 코드에서 호출할 때는 캐싱할 콘텐츠 블록에 cache_control를 추가하고, 네이티브 /v1/messages를 사용하세요. OpenAI 호환 인터페이스는 현재 캐싱하지 않습니다.
히트 여부를 확인하려면 응답의 usage.cache_read_input_tokens가 0보다 큰지만 확인하면 됩니다.
캐시는 기본적으로 5분간 유지되며, 히트할 때마다 타이머가 초기화됩니다. "ttl": "1h"를 사용하면 더 높은 쓰기 단가로 1시간짜리 캐시를 쓸 수 있습니다.

활성화 방법

system, tools, messages의 콘텐츠 블록에 "cache_control": {"type": "ephemeral"}를 추가하면 해당 블록과 그 앞의 모든 내용이 캐시됩니다. 한 요청에 최대 4개의 캐시 브레이크포인트를 둘 수 있습니다.

1
curl https://1zheai.com/v1/messages \
2
  -H "x-api-key: $ONEZHE_API_KEY" \
3
  -H "anthropic-version: 2023-06-01" \
4
  -H "content-type: application/json" \
5
  -d '{
6
    "model": "claude-sonnet-5-5",
7
    "max_tokens": 256,
8
    "system": [
9
      {
10
        "type": "text",
11
        "text": "这里放一段很长、每次都一样的内容：项目说明、代码规范、参考文档……",
12
        "cache_control": {"type": "ephemeral"}
13
      }
14
    ],
15
    "messages": [{"role": "user", "content": "根据上面的规范，审查这段代码：..."}]
16
  }'

캐싱할 접두사가 너무 짧으면 요청은 정상적으로 처리되지만 캐시되지 않으며, 오류도 발생하지 않습니다. 최소 길이는 모델마다 다르며 아래 표를 참조하세요.

최소 캐시 가능 길이

다음은 Anthropic 공식 문서(2026-10-14) 기준입니다:

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

히트 확인 방법

같은 요청을 두 번(5분 이내 간격으로) 보내고 두 응답의 usage를 비교하세요. 아래는 2026-10-15에 claude-sonnet-5-5로 측정한 실제 결과이며, 시스템에 약 18,000 토큰의 고정 텍스트가 들어 있습니다:

第一次：写入缓存
第二次：命中缓存

{
  "input_tokens": 23,
  "cache_creation_input_tokens": 17920,
  "cache_read_input_tokens": 0,
  "cache_creation": {"ephemeral_5m_input_tokens": 17920, "ephemeral_1h_input_tokens": 0},
  "output_tokens": 4
}

{
  "input_tokens": 23,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 17920,
  "cache_creation": {"ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 0},
  "output_tokens": 4
}

두 번째 cache_read_input_tokens가 0보다 크면 캐시가 읽히고 있는 것입니다. 각 호출의 캐시 쓰기/읽기 토큰은 호출 로그의 토큰 열에도 표시되며, 읽기는 “cache↓”, 쓰기는 ”↑“로 기록됩니다.

과금 방식

유형	공식 단가	1折AI 단가
캐시 쓰기 (5분)	입력 가격 × 1.25	공식 정가, 할인 없음
캐시 쓰기 (1시간)	입력 가격 × 2	공식 정가, 할인 없음
캐시 읽기	입력 가격 × 0.1 (Opus 5.5와 Sonnet 5.5는 0.05, Fable 5.1은 0.025)	공식 정가, 할인 없음

5분 캐시 쓰기의 공식 가격은 보통 공식 입력 가격의 1.25배입니다. 이 사이트는 입력에는 할인이 있지만 캐싱에는 할인이 없으므로, 공식 배수만으로 캐시 읽기 한 번이 본전이라는 결론을 내릴 수 없습니다. 모델 할인율, 쓰기 비용, 반복 읽기 횟수를 비교해야 합니다. 전체 계산 예시는 가격 및 과금에 있습니다.

1시간 캐시

"ttl": "1h"에 cache_control를 추가하면 캐시가 1시간 유지됩니다. 간격이 5분을 넘지만 계속 반복 사용되는 접두사에 적합합니다:

1
"cache_control": {"type": "ephemeral", "ttl": "1h"}

쓰기는 공식 입력 가격의 2배로 과금되며 할인된 입력 가격이 아니고, 읽기는 5분 캐시와 동일합니다. 쓰여진 토큰은 응답의 cache_creation.ephemeral_1h_input_tokens에 표시됩니다. 1시간 캐시를 선택할지는 두 요청 간의 간격, 쓰기 비용, 반복 읽기 횟수를 기준으로 판단하세요.

Claude Code의 캐싱

Claude Code는 시스템 프롬프트, 도구 정의, 대화 기록에 자동으로 캐시 브레이크포인트를 배치합니다. 공식 설명은 여기입니다. 히트율을 높이려면:

한 세션 안에서 계속 작업하세요. 중간에 오래 멈추지 마세요. 5분간 사용하지 않으면 캐시가 만료됩니다.
같은 세션의 이후 요청은 캐시를 읽습니다. 2026-10-15 측정 기준, 2라운드 Claude Code 작업에서 2라운드는 캐시 31,440 토큰을 읽고 115 토큰을 썼습니다. 새 세션을 시작하면 1라운드에서 접두사를 통째로 다시 써야 할 수 있으며(약 30,000 토큰 측정), 그 호출은 이후 호출보다 비쌉니다.
세션 중간에 CLAUDE.md 변경, MCP 서버 전환, 모델 변경을 피하세요. 모두 접두사를 바꿉니다.
DISABLE_PROMPT_CACHING=1를 설정하지 마세요. 이 환경 변수는 모든 모델의 캐싱을 끕니다.

OpenAI 호환 인터페이스에서도 캐싱을 쓸 수 있나요?

현재는 불가능합니다. 2026-10-15 측정 기준, /v1/chat/completions의 시스템 메시지에 약 3,100 토큰의 고정 텍스트를 넣고 연속으로 두 번 보냈을 때, 콘텐츠 블록에 cache_control를 넣었는지와 관계없이 두 응답의 usage는 다음과 같았습니다:

1
{"prompt_tokens": 3167, "completion_tokens": 4, "total_tokens": 3171}

prompt_tokens_details.cached_tokens가 없고 호출 로그의 캐시 읽기/쓰기도 모두 0이며, 요청 전체가 입력 가격으로 과금됩니다. 캐싱이 필요한 시나리오는 /v1/messages(Anthropic SDK 또는 Claude Code)를 사용하세요.

FAQ

왜 항상 cache_creation만 있고 cache_read는 없나요?

캐시는 썼는데 다음 요청이 읽지 못했습니다. 순서대로 점검하세요: 두 요청 간격이 5분을 넘었는지, 브레이크포인트 앞 내용이 바이트 단위로 완전히 동일한지(시스템의 타임스탬프와 랜덤 ID는 매번 다르게 만듭니다), 모델을 바꿨는지, 접두사가 위의 최소 길이에 도달했는지.

캐시 적중률을 볼 수 있나요?

각 호출의 캐시 읽기/쓰기 토큰은 호출 로그에 있으니 직접 계산할 수 있습니다: 캐시 읽기 ÷ (입력 + 캐시 쓰기 + 캐시 읽기).