Prompt Caching 비용 가이드: Cache Hits, Prefixes, 그리고 실제 API 비용

프롬프트 캐싱 비용은 헤드라인에 적힌 할인율이 아니라, 두 번째 요청이 첫 번째 요청과 정확히 일치하는지에 따라 달라집니다. claude-sonnet-5에서 20,000토큰 시스템 프롬프트를 사용할 경우, 1,000번의 요청 비용은 캐싱을 하지 않았을 때 약 $18.18이지만, 첫 번째 요청 이후 모든 요청이 캐시를 적중하면 약 $2.00가 됩니다. 만약 호출할 때마다 접두사가 변경된다면, 캐싱을 하지 않은 기본 비용보다 더 많은 비용이 발생합니다. 이 가이드는 2026년 10월 3일에 관찰된 TokenLab 가격을 사용하여 그 기준점이 어디에 있는지 보여주며, 문서에서 확인할 수 없었던 부분들을 표시합니다.

핵심 요약

• 조사한 5개 모델에서 캐시 읽기 비용은 일반 입력 가격의 2%에서 10% 수준입니다. 5개 모델 중 2개는 캐시 쓰기 가격이 명시되어 있지 않습니다.
• 쓰기 가격이 존재하는 경우, 입력 가격과 동일하거나(deepseek-v4.1-flash) 입력 가격의 1.25배(claude-sonnet-5, claude-sonnet-5-5)입니다.
• 계산상, 쓰기당 한 번의 캐시 적중이 있으면 1.25배의 쓰기 프리미엄을 상쇄할 수 있습니다. 이는 캐시 항목이 유지된다는 가정하에 성립하며, 우리가 읽은 자료에는 캐시 유지 기간이 명시되어 있지 않았습니다.
• 캐싱은 청구서의 입력 측 비용만 줄여줍니다. 출력 토큰은 이전과 동일하게 가격이 책정됩니다.
• 우리가 읽은 TokenLab API 문서에는 usage 필드 내에 캐시된 토큰 필드가 명시되어 있지 않습니다. 자체 테스트에서 원본 객체를 로그로 남겨 Usage와 대조해 보십시오.

모델별 프롬프트 캐싱 비용: 읽기, 쓰기 및 입력 가격

2026년 10월 3일 각 모델의 라이브 모델 API를 확인했습니다. 5개 모델 모두 기능 목록에 prompt-cache가 포함되어 있으며, 가격은 2026년 10월 2일 16:53:30.068Z에 마지막으로 업데이트되었습니다. 가격은 100만 토큰당 USD 기준입니다.

모델	입력	캐시 읽기	캐시 쓰기	입력 대비 읽기 비율	입력 대비 쓰기
claude-sonnet-5	0.90	0.09	1.125	10%	1.25배
claude-sonnet-5-5	0.60	0.06	0.75	10%	1.25배
gpt-5.5	1.50	0.15	명시되지 않음	10%	명시되지 않음
deepseek-v4.1-flash (비피크 시간대)	0.15	0.003	0.15	2%	1.0배
deepseek-v4.1-flash (피크 시간대)	0.30	0.006	0.30	2%	1.0배
gemini-3.8-flash	0.375	0.0375	명시되지 않음	10%	명시되지 않음

두 개의 백분율 열은 명시된 가격을 직접 나눈 값입니다.

출처 (모두 2026년 10월 3일 관찰):

• claude-sonnet-5 (모델 페이지: /models/claude-5/claude-sonnet-5)
• claude-sonnet-5-5 (모델 페이지: /models/claude-5/claude-sonnet-5-5)
• gpt-5.5 (모델 페이지: /models/gpt-5-5/gpt-5.5)
• deepseek-v4.1-flash (모델 페이지: /models/deepseek-v4/deepseek-v4.1-flash)
• gemini-3.8-flash (모델 페이지: /models/gemini-3/gemini-3.8-flash)

이 표를 읽을 때 세 가지 세부 사항이 중요합니다.

첫째, gpt-5.5와 gemini-3.8-flash는 캐시 읽기 가격은 있지만 캐시 쓰기 가격은 없습니다. 이 데이터만으로는 첫 번째 접두사가 어떻게 청구되는지 알 수 없습니다. 증거 자료에는 이것이 무료라고 되어 있지 않으며, 입력 요율로 청구된다고도 되어 있지 않습니다. 어느 쪽 가정을 바탕으로 예측을 세우기 전에 첫 번째 요청 후 Usage를 확인하십시오.

둘째, deepseek-v4.1-flash를 읽었을 때 두 개의 가격 항목을 발견했습니다. off-peak 항목(선택자 offPeak: true)과 peak 항목(offPeak: false)은 모든 라인에서 2배 차이가 납니다. 토큰당 캐시 절감액의 백분율은 동일하지만, 피크 시간대에는 절대적인 금액이 두 배가 됩니다.

셋째, 이는 TokenLab의 공개 가격입니다. 결제 가이드(2026년 10월 3일 관찰)에 따르면 완료된 요청은 해당 요청을 생성한 전달 옵션에 대해 한 번 청구됩니다. Official은 모델 제작사의 공개 가격을 따르므로, 제작사의 가격표와 비교하기 전에 어떤 옵션이 귀하의 요청을 처리했는지 확인하십시오.

Get a Model 참조에는 prompt-cache 기능을 가진 gpt-5.6-terra가 나와 있습니다. 예시 응답에 가격이 포함되어 있지 않아 해당 모델은 표에서 제외했습니다. 카탈로그에 있는 다른 모델들은 확인하지 않았습니다.

프롬프트 캐싱 비용 예시: 긴 시스템 프롬프트 하나

다음은 시나리오이며, 모든 입력값이 명시되어 있어 자신의 수치로 교체할 수 있습니다. 이는 측정값이 아닌 우리의 가정입니다.

• 모든 요청에서 동일한 20,000토큰 시스템 프롬프트 및 도구 블록.
• 요청마다 변경되는 200토큰 사용자 메시지.
• 1,000번의 요청, 캐시가 전체 실행 동안 유지되어 1번의 쓰기와 999번의 읽기가 발생.
• 출력 토큰은 캐싱 여부와 관계없이 비용이 동일하므로 무시함.

claude-sonnet-5 (100만 토큰당 입력 0.90, 읽기 0.09, 쓰기 1.125):

• 캐싱 미사용: 1,000 × 20,200 = 20,200,000 토큰 × $0.90/1M = $18.18
• 캐시 쓰기: 20,000 × $1.125/1M = $0.0225
• 캐시 읽기: 999 × 20,000 = 19,980,000 × $0.09/1M = $1.7982
• 캐싱 미사용 접미사: 1,000 × 200 = 200,000 × $0.90/1M = $0.18
• 캐싱 사용: 0.0225 + 1.7982 + 0.18 = 약 $2.00, 캐싱 미사용 대비 약 89% 절감

이제 실패 사례입니다. 호출할 때마다 접두사가 약간씩 변경되어 각 요청마다 쓰기 비용을 지불하고 읽기는 전혀 발생하지 않는 경우입니다. 이 경우 접두사 비용으로 1,000 × 20,000 × $1.125/1M = $22.50가 발생하며, 접미사 비용 $0.18이 추가됩니다. 총합은 약 $22.68로, 캐싱 미사용 시의 $18.18보다 $4.50(25%) 더 높습니다.

손익분기점은 동일한 가격에서 도출됩니다. 100만 접두사 토큰당 쓰기 비용은 일반 입력보다 $0.225 더 비싸고, 각 읽기는 $0.81을 절약합니다. 한 번의 적중으로 쓰기 비용을 상쇄하고도 남습니다(0.225 ÷ 0.81 ≈ 쓰기당 0.28회 읽기).

다른 모델에서의 동일 시나리오:

모델	캐시 미사용	캐시 사용 (예상)	첫 번째 요청에 대한 가정
claude-sonnet-5	$18.18	$2.00	명시된 쓰기 가격
claude-sonnet-5-5	$12.12	$1.33	명시된 쓰기 가격
deepseek-v4.1-flash 비피크	$3.03	$0.09	명시된 쓰기 가격
deepseek-v4.1-flash 피크	$6.06	$0.19	명시된 쓰기 가격
gpt-5.5	$30.30	$3.33	쓰기 가격 없음; 20,000토큰을 입력 요율로 계산
gemini-3.8-flash	$7.58	$0.83	쓰기 가격 없음; 20,000토큰을 입력 요율로 계산

gpt-5.5의 경우 계산식은 20,000 × $1.50/1M = $0.03, 더하기 19,980,000 × $0.15/1M = $2.997, 더하기 200,000 × $1.50/1M = $0.30입니다. 표시된 두 행은 증거가 뒷받침하지 않는 가정에 근거하므로 대략적인 수치로 간주하십시오.

프롬프트를 캐시 가능하게 만들기: 문서가 확인해 주는 것

증거 자료는 짧은 요구 사항 목록을 뒷받침합니다.

1. prompt-cache가 나열된 모델을 선택하십시오. Get a Model에서 가져온 capabilities 배열(2026년 10월 3일 관찰)이 확인 기준입니다. 해당 기능이 없는 모델은 할인을 기대할 근거가 없습니다.
2. 공유 콘텐츠를 안정적인 위치에 유지하십시오. Messages 엔드포인트에서 system은 최상위 필드이며 문자열이나 콘텐츠 블록 배열을 받습니다. Chat Completions에서는 시스템 지침이 messages에 들어갑니다. 어느 쪽이든 반복되는 자료가 먼저 와야 합니다.
3. 경계까지 동일한 바이트를 전송하십시오. 이는 이 기사 원본의 정확한 접두사 규칙이며, 표의 가격 책정 방식과 일치합니다. 읽기 가격은 프롬프트 중 일치하는 부분에만 적용됩니다.

Request A: [ System Prompt + Tool Definitions ] [ User Query A ]
           ▲───────────── CACHED PREFIX ────────▲ ▲── SUFFIX ──▲

Request B: [ System Prompt + Tool Definitions ] [ User Query B ]
           ▲─────────── CACHE HIT (READ) ───────▲ ▲── SUFFIX ──▲

재사용을 가장 자주 방해하는 세 가지 습관:

• 시스템 프롬프트 상단의 타임스탬프, 사용자 ID 또는 세션 ID.
• 요청 간에 도구 정의나 JSON 키의 순서가 바뀐 경우.
• 공유 텍스트 내의 들여쓰기나 줄바꿈 변경.

Create Message 참조에 문서화된 요청 형태:

{
  "model": "claude-sonnet-5",
  "max_tokens": 512,
  "system": [
    {
      "type": "text",
      "text": "You are a support assistant. The following policy governs all responses: [Full Policy Text]"
    }
  ],
  "messages": [
    { "role": "user", "content": "What is the return period for damaged items?" }
  ]
}

이 기사의 이전 초안에는 해당 시스템 블록에 ephemeral 유형의 cache_control 마커가 있었습니다. 2026년 10월 3일에 읽은 Create Message 참조에는 해당 필드가 나열되어 있지 않아 샘플에서 제거했습니다. 최소 접두사 길이와 캐시 유지 기간도 마찬가지입니다. 우리가 읽은 TokenLab 문서에서는 그 수치를 찾을 수 없었습니다. 명시적 마커나 TTL에 의존하기 전에, 선택한 모델을 테스트하고 두 번의 동일한 호출에서 캐시된 토큰 수를 비교해 보십시오.

캐시 가격 읽기 및 캐시된 토큰 확인

위의 표를 코드로 복사하지 마십시오. 결제 가이드에 따르면 애플리케이션이 필요할 때 현재 가격을 읽어야 합니다. 문서화된 두 가지 경로:

curl "https://api.tokenlab.sh/v1/models/claude-sonnet-5"
curl "https://api.tokenlab.sh/v1/pricing?provider=openai&tag=chat"

첫 번째는 모델의 기능, 제한 사항 및 가격을 반환합니다. 알 수 없는 모델 ID는 404 model_not_found를 반환합니다. 두 번째는 API 키가 필요 없는 공개 엔드포인트입니다. 문서화된 샘플 응답에는 gpt-4o에 대한 input_per_1m_tokens와 output_per_1m_tokens가 표시되지만 캐시 필드는 없습니다. 해당 샘플의 updated_at은 2026년 4월 20일로, 현재 가격이 아닌 샘플 데이터입니다. 캐시 가격은 모델별 엔드포인트를 사용했습니다.

캐싱이 작동했는지 확인하기 위해 문서화된 usage 객체는 기대보다 더 간략합니다. Chat Completions는 prompt_tokens, completion_tokens, total_tokens를 나열합니다. Messages는 input_tokens와 output_tokens를 나열합니다. 어느 참조에도 캐시된 토큰 필드는 명시되어 있지 않습니다. 코딩 에이전트 비용 가이드(2026년 10월 3일 관찰)는 응답이나 Usage에서 캐시된 토큰 사용량을 확인하고, 작업당 입력, 출력 및 캐시된 토큰을 기록하라고 안내합니다.

우리가 실행할 테스트:

1. 마지막 사용자 메시지만 변경하여 동일한 긴 접두사 요청을 몇 초 간격으로 두 번 보냅니다.
2. 두 응답에서 전체 원본 usage 객체와 billing_transaction_id(있는 경우)를 로그로 남깁니다.
3. Usage에서 두 번째 요청의 청구 금액을 위의 계산식과 비교합니다. 캐시 적중은 캐싱 미사용 수치가 아닌 "캐싱 사용" 수치에 가까워야 합니다.
4. 첫 번째 줄을 의도적으로 변경하여 적중 실패 비용을 확인합니다.

스트리밍 Chat Completions의 경우 stream_options.include_usage: true를 설정하여 스트림 청크 내에서 사용량을 수신하십시오. 스트림에서는 결제 헤더가 없을 수 있으므로 최종 청구 금액은 Usage를 사용하십시오. 문제 해결 가이드는 또한 서버 측 조정을 위해 model, startDate, endDate로 필터링하는 GET /v1/management/api-keys/{keyId}/usage를 설명합니다.

프롬프트 캐싱 비용이 효과적이지 않은 경우

캐싱은 반복되는 트래픽에 대한 베팅입니다. 다음과 같은 상황에서는 손해를 봅니다:

• 접두사가 반복되지 않는 경우. 일회성 20,000토큰 문서는 쓰기 프리미엄을 지불하고 아무것도 돌려받지 못합니다.
• 요청이 너무 느리게 도착하는 경우. 일치하는 요청 간의 간격이 캐시 유지 기간을 초과하면 모든 호출이 새로운 쓰기가 됩니다. 증거 자료에서 해당 유지 기간을 찾지 못했으므로, 모델 페이지에 명시된 내용과 비교하여 자신의 간격을 측정하십시오.
• 경계 이전에 접두사가 변경되는 경우. 위 실패 사례의 25% 초과 지출은 정확히 이 패턴에서 발생합니다.
• 접두사가 작은 경우. 절감액은 접두사 토큰에 비례합니다. 수백 개의 토큰은 호출당 몇 센트의 일부를 절약할 뿐이며, 캐시 가능한 최소 크기는 증거 자료에 없습니다.
• 출력이 비용의 대부분을 차지하는 경우. 캐싱은 입력만 줄입니다. 답변이 길면 캐시 라인은 전체 비용의 작은 부분만 이동시킵니다.
• 모델에 캐시 가격이 없는 경우. 결제 가이드에 따르면 TokenLab 가격 열의 대시는 검증된 제안이 없음을 의미하며 무료가 아닙니다. 할인을 기대하기 전에 모델의 가격 세부 정보를 확인하십시오.

워크로드 패턴	캐싱 적합성	이유
다중 턴 도구 루프	높음	지침과 도구 정의가 단계 전반에 걸쳐 고정됨.
많은 사용자가 하나의 큰 문서를 쿼리	높음	트래픽 급증이 쓰기 비용을 빠르게 상쇄함.
드문 백그라운드 작업	낮음	캐시 유지 기간보다 긴 간격은 반복적인 쓰기를 강제함.
다양한 시스템 프롬프트	낮음	경계 이전의 변경 사항이 일치를 깨뜨림.

프롬프트 캐싱은 결제 가이드의 "캐싱 구현" 팁과는 다릅니다. 이는 반복되는 동일한 요청에 대해 자체 앱에 응답을 저장하는 것을 의미합니다. 이는 모델 호출을 완전히 피할 수 있게 하지만 전체 요청이 반복될 때만 도움이 됩니다. 긴 에이전트 세션의 경우 코딩 에이전트 비용 가이드가 캐싱과 함께 컨텍스트 크기, 출력 제한 및 모델 선택을 다룹니다.

FAQ

캐시 적중이 항상 요청을 더 저렴하게 만드나요?

일치하는 접두사에 대해서만, 그리고 모델이 캐시 읽기 가격을 나열한 경우에만 그렇습니다. 우리가 확인한 모델에서 읽기 비용은 입력의 2%에서 10%입니다. 접미사와 모든 출력 토큰은 일반 요율로 청구됩니다. 쓰기 프리미엄이 있는 모델에서 적중 실패 시 캐싱을 하지 않은 호출보다 더 많은 비용이 발생할 수 있습니다.

캐시 쓰기 가격이 없으면 무료인가요?

아니요. gpt-5.5와 gemini-3.8-flash의 경우, 2026년 10월 3일 라이브 API에 캐시 읽기 가격은 있었지만 쓰기 가격은 없었습니다. 0이나 입력 요율이라고 가정하기보다 첫 번째 요청을 실행하고 Usage에서 청구 금액을 확인하십시오.

캐시 가능한 프롬프트에서 사용자별 값은 어디에 두어야 하나요?

공유 콘텐츠 이후, 사용자 메시지나 나중의 messages 항목에 두십시오. 공유 블록 이전에 변경되는 모든 것은 접두사를 변경하고 새로운 쓰기를 강제합니다. 여기에는 타임스탬프, 세션 ID, 재정렬된 도구 목록이 포함됩니다.

반복된 요청에서 캐시된 토큰이 표시되지 않는 이유는 무엇인가요?

다음 네 가지를 순서대로 확인하십시오. 모델이 prompt-cache를 나열합니까? 접두사가 호출 간에 바이트 단위로 동일합니까? 두 번째 호출이 캐시 유지 기간 내에 도착했습니까? 캐시된 카운트가 로그에서 삭제되는 필드에 있습니까? 우리가 읽은 문서에는 해당 필드 이름이 없으므로 전체 usage 객체를 로그로 남기십시오.

모델을 결정하기 전에 TokenLab 모델 페이지에서 실시간 캐시 가격을 비교하십시오.