Claude Code 프롬프트 캐싱 TTL 완전 분석: 5분 vs 1시간 무엇을 선택해야 할까? 3개 플랫폼 요금 비교 포함

작성자 주: Claude Code 프롬프트 캐싱의 TTL 메커니즘, 5분과 1시간 설정의 차이, Anthropic API와 AWS Bedrock의 캐싱 비용 비교 및 비용 절감 설정 팁을 상세히 설명합니다.

「Claude Code의 프롬프트 캐싱 TTL을 변경할 수 있나요? 5분과 1시간은 어떤 차이가 있죠? 어떤 게 더 경제적인가요?」—— 이는 많은 Claude Code 사용자가 비용을 관리할 때 가장 자주 묻는 질문입니다.

결론부터 말씀드리면, Claude Code의 캐싱 TTL은 현재 사용자가 직접 수정할 수 없으며 구독 플랜에 따라 결정됩니다. Max 구독 사용자는 1시간 TTL을 자동으로 제공받으며, Pro 구독 및 API 키 사용자는 기본적으로 5분 TTL이 적용됩니다. 하지만 Claude API를 직접 호출하는 경우 cache_control 파라미터를 통해 5분 또는 1시간 중 자유롭게 선택할 수 있습니다.

핵심 가치: 이 글을 읽고 나면 Claude 프롬프트 캐싱의 TTL 메커니즘을 완벽히 이해하고, Anthropic 공식 API와 AWS Bedrock의 캐싱 비용 차이를 파악하여 사용 환경에 맞는 가장 경제적인 캐싱 전략을 세울 수 있게 됩니다.

Claude 프롬프트 캐싱 TTL 핵심 요약

프롬프트 캐싱은 Claude 시리즈 모델에서 가장 중요한 비용 절감 메커니즘 중 하나입니다. 이전에 전송했던 프롬프트 접두사(시스템 프롬프트, 도구 정의, 대화 기록 등)를 서버에 저장하여, 다음 요청 시 접두사가 동일하면 캐시에서 직접 불러와 일반 입력 비용의 **10%**만 지불하면 됩니다.

Claude Code의 TTL을 변경할 수 있나요?

사용자들이 가장 궁금해하는 부분입니다. 두 가지 경우로 나뉩니다.

Claude Code(대화형 CLI 도구): 수동 수정 불가. Claude Code의 캐싱은 서버 측에서 제어됩니다. Max 구독 사용자는 1시간 TTL을 제공받으며(서버 측 기능 플래그 tengu_prompt_cache_1h_config로 제어), Pro 구독 및 API 키 사용자는 5분 TTL이 적용됩니다. 환경 변수 DISABLE_PROMPT_CACHING=1을 통해 캐싱을 완전히 끌 수는 있지만, TTL 단계를 전환할 수는 없습니다.

Claude API(직접 호출): 자유롭게 선택 가능. API를 통해 호출할 때는 cache_control 파라미터에서 TTL을 지정할 수 있습니다.

// 5분 캐싱(기본값)
{ "cache_control": { "type": "ephemeral" } }

// 1시간 캐싱
{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }

🎯 선택 제안: 주로 Claude Code CLI를 사용한다면 TTL은 구독 플랜에 따라 결정됩니다. API를 통해 호출한다면(APIYI apiyi.com 등 활용), 상황에 따라 5분 또는 1시간 TTL을 유연하게 선택하여 더욱 정밀한 비용 관리를 실현할 수 있습니다.

Claude 프롬프트 캐싱 TTL 과금 규칙 상세 분석

5분 vs 1시간: 과금 비교

두 TTL 설정의 핵심 차이는 쓰기 비용에 있습니다. 읽기 비용은 기초 입력 가격의 0.1배로 동일합니다.

모델별 프롬프트 캐싱 상세 가격

다음은 Anthropic 공식 API의 모델별 전체 캐싱 과금 표입니다 (2026년 3월 기준):

핵심 발견: 캐시 읽기 할인이 매우 큽니다. Claude Opus 4.6을 예로 들면:

• 일반 입력 100만 토큰 = $5.00
• 캐시 읽기 100만 토큰 = $0.50 ($4.50 절약, 90% 할인)
• 이것이 바로 Claude Code Pro 월 $20 요금제가 경제적인 이유입니다. 캐싱 없이 Opus 대화 100회를 진행하면 $50-100가 들 수 있지만, 캐싱을 사용하면 $10-19 정도로 충분합니다.

최소 캐싱 토큰 수 제한

모든 내용을 캐싱할 수는 없습니다. 모델별로 최소 토큰 수 제한이 있어, 내용이 너무 짧으면 캐싱이 트리거되지 않습니다.

🎯 실용 팁: 시스템 프롬프트가 짧다면(예: 2,048 토큰 미만), Claude Sonnet 4.6 사용 시 캐싱이 트리거되지 않습니다. 시스템 프롬프트 내용을 보강하거나 도구 정의를 병합하여 최소 기준을 충족해 보세요. APIYI(apiyi.com)를 통해 호출해도 캐싱을 완벽하게 지원하며, 더 합리적인 요금으로 이용할 수 있습니다.

Anthropic API vs AWS Bedrock: 캐싱 과금 비교

3대 플랫폼 캐싱 지원 비교

Claude의 프롬프트 캐싱은 Anthropic 공식 API, AWS Bedrock, Google Vertex AI 세 플랫폼 모두에서 지원하지만 세부 사항에는 차이가 있습니다.

플랫폼별 주요 차이점

Anthropic 공식 API: 캐싱 기능이 가장 완벽하며, 모든 모델에서 5분 및 1시간 TTL을 지원합니다. 2026년 2월 5일부터 캐시 격리 단위가 조직 수준에서 워크스페이스 수준으로 변경되어, 동일 조직 내 워크스페이스 간 캐시는 독립적으로 운영됩니다.

AWS Bedrock: 2026년 1월부터 1시간 TTL 지원을 발표했으나, Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 등 일부 모델로 제한됩니다. 최신 Claude Sonnet 4.6과 Opus 4.6의 Bedrock 1시간 TTL 지원 여부는 확인이 필요합니다. Claude Code로 Bedrock을 연결할 경우 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 호환성 설정에 주의하세요.

Google Vertex AI: 캐싱 기능은 공식 API와 거의 동일하지만, Google Cloud 프로젝트를 통한 인증 및 과금이 필요합니다.

🎯 플랫폼 선택 제안: 플랫폼 간 차이나 복잡한 설정이 번거롭다면 APIYI(apiyi.com)의 통합 인터페이스를 사용하는 것이 가장 간편합니다. 별도의 AWS IAM이나 Google Cloud 인증 없이도 전체 캐싱 기능을 지원하며, 비용 효율적인 모델 호출이 가능합니다.

Claude Code 프롬프트 캐싱 빠르게 시작하기

초간단 예제: 1시간 TTL 캐시 설정

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://vip.apiyi.com/v1"
)

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[{
        "type": "text",
        "text": "당신은 고등학교 물리 문제를 해결하는 전문 물리 교사 보조입니다...(긴 시스템 프롬프트)",
        "cache_control": {"type": "ephemeral", "ttl": "1h"}
    }],
    messages=[{"role": "user", "content": "뉴턴 제3법칙을 설명해줘"}]
)
print(f"캐시 읽기 토큰: {response.usage.cache_read_input_tokens}")
print(f"캐시 쓰기 토큰: {response.usage.cache_creation_input_tokens}")

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://vip.apiyi.com/v1"
)

# 혼합 TTL: 시스템 프롬프트는 1시간(자주 안 바뀜), 대화 컨텍스트는 5분(자주 바뀜)
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    system=[
        {
            "type": "text",
            "text": "당신은 전문 AI 기술 컨설턴트입니다...(긴 시스템 프롬프트, 2000+ 토큰)",
            "cache_control": {"type": "ephemeral", "ttl": "1h"}  # 시스템 프롬프트는 1시간
        },
        {
            "type": "text",
            "text": "다음은 사용자의 이전 대화 컨텍스트입니다...(대화 기록)",
            "cache_control": {"type": "ephemeral"}  # 대화 컨텍스트는 5분(기본값)
        }
    ],
    messages=[{"role": "user", "content": "Claude와 GPT의 추론 능력을 비교해줘"}]
)

# 캐시 사용량 확인
usage = response.usage
print(f"일반 입력 토큰: {usage.input_tokens}")
print(f"캐시 읽기 토큰: {usage.cache_read_input_tokens}")
print(f"캐시 쓰기 토큰: {usage.cache_creation_input_tokens}")

# 비용 절감액 계산 (Sonnet 4.6 기준)
base_cost = (usage.input_tokens / 1_000_000) * 3
cache_cost = (usage.cache_read_input_tokens / 1_000_000) * 0.3
saved = (usage.cache_read_input_tokens / 1_000_000) * 2.7
print(f"이번에 절약한 금액: ${saved:.4f}")

중요 제약 사항: 하나의 요청에서 두 가지 TTL을 혼합 사용할 경우, 1시간 캐시 내용을 5분 캐시 내용보다 앞에 배치해야 합니다. 그렇지 않으면 오류가 발생합니다.

팁: APIYI(apiyi.com)를 통해 Claude API를 호출하면 cache_control 파라미터 설정을 완벽하게 지원하며, 5분과 1시간 TTL을 자유롭게 선택할 수 있습니다.

5분 vs 1시간 TTL: 무엇을 선택할까요?

선택 가이드

비용 계산 공식

캐시가 효율적인지 판단하는 핵심 공식입니다:

5분 TTL 손익분기점: 캐시 내용이 5분 내에 최소 1번 읽힐 때

• 쓰기 비용: 1.25배 → 추가 0.25배
• 읽기 절감: 매번 0.9배 절약
• 1번 읽기만 해도 이득 (0.9 > 0.25)

1시간 TTL 손익분기점: 캐시 내용이 1시간 내에 최소 2번 읽힐 때

• 쓰기 비용: 2.0배 → 추가 1.0배
• 읽기 절감: 매번 0.9배 절약
• 2번 읽어야 이득 (0.9 × 2 = 1.8 > 1.0)

자주 묻는 질문 (FAQ)

요약

Claude 프롬프트 캐시 TTL의 핵심 포인트:

1. 두 가지 TTL 옵션: 5분(쓰기 1.25배, 1회 읽기로 본전)과 1시간(쓰기 2배, 2회 읽기로 본전)이 있으며, 읽기 비용은 모두 0.1배입니다.
2. Claude Code CLI는 TTL 변경 불가: Max 구독은 1시간 자동 적용, Pro/API 키는 5분 고정이며 변경할 수 없습니다.
3. Claude API는 자유롭게 선택 가능: cache_control.ttl 파라미터로 설정하며, 동일한 요청 내에서도 두 가지 TTL을 혼합할 수 있습니다.
4. 고빈도 대화는 5분 추천: 매번 적중 시 자동으로 연장되어 쓰기 비용이 더 저렴합니다. 간헐적으로 사용한다면 만료를 방지하기 위해 1시간을 선택하세요.

캐시 적중은 입력 비용을 1/10로 줄여주는 Claude의 핵심 절약 메커니즘입니다. APIYI(apiyi.com)의 통합 인터페이스를 통해 호출하면 캐시 설정을 완벽하게 지원하며, 하나의 키로 다양한 TTL 전략의 실제 비용 차이를 쉽게 테스트할 수 있습니다.

📚 참고 자료

1. Anthropic 공식 문서 – 프롬프트 캐싱(Prompt Caching): TTL 설정, 과금 규칙, cache_control 문법에 대한 권위 있는 정보원

   • 링크: platform.claude.com/docs/en/build-with-claude/prompt-caching
   • 설명: 5분/1시간 TTL에 대한 전체 과금 공식 및 코드 예제

2. Anthropic 공식 문서 – 가격 정책: 모든 모델의 기본 가격 및 캐싱 가격

   • 링크: platform.claude.com/docs/en/about-claude/pricing
   • 설명: Opus/Sonnet/Haiku 각 모델의 캐시 쓰기 및 읽기 요금

3. AWS 공식 문서 – Bedrock 프롬프트 캐싱: Bedrock 플랫폼의 캐싱 지원 세부 정보

   • 링크: docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html
   • 설명: Bedrock에서 각 모델의 TTL 지원 범위 및 과금 기준

4. Claude Code Camp – 프롬프트 캐싱 작동 원리: Claude Code의 캐싱 구현 방식 심층 분석

   • 링크: claudecodecamp.com/p/how-prompt-caching-actually-works-in-claude-code
   • 설명: Claude Code가 어떻게 캐시 중단점을 자동으로 관리하는지 확인해 보세요

5. GitHub Issue #19436 – 다층 캐시 TTL 기능 요청: 더 유연한 TTL 설정을 위한 커뮤니티 논의

   • 링크: github.com/anthropics/claude-code/issues/19436
   • 설명: 콘텐츠 변경 빈도에 기반한 다층 TTL 솔루션에 대한 커뮤니티 제안

작성자: APIYI 기술팀
기술 교류: Claude 캐싱 설정 경험을 댓글로 자유롭게 공유해 주세요. 더 많은 모델 호출 튜토리얼은 APIYI docs.apiyi.com 문서 센터에서 확인하실 수 있습니다.