---
title: "프롬프트 캐싱 사용법과 과금"
description: "1折AI에서 Claude 프롬프트 캐싱 사용법: 활성화 방법, 최소 길이, 히트 확인 방법, 히트 과금 방식, Claude Code의 캐싱 동작."
headingIds: {"결론부터":"section-1","활성화 방법":"section-2","최소 캐시 가능 길이":"section-3","히트 확인 방법":"section-4","과금 방식":"section-5","1시간 캐시":"section-6","Claude Code의 캐싱":"section-7","OpenAI 호환 인터페이스에서도 캐싱을 쓸 수 있나요?":"section-8","FAQ":"section-9"}
---

<aside className="docs-publication" data-pagefind-ignore>

[1ZheAI](https://1zheai.com/en/editorial/#publisher)가 관리하는 문서입니다. [출처 및 수정 사항](https://1zheai.com/en/editorial/).

오류를 발견하셨나요? 페이지 주소와 설명을 첨부하여 [고객 지원](mailto:support@1zheai.com)으로 문의해 주세요. API 키나 계정 정보는 보내지 마세요.

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

## 결론부터

- **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개의 캐시 브레이크포인트를 둘 수 있습니다.

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

<Note>

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

</Note>

## 최소 캐시 가능 길이

다음은 [Anthropic 공식 문서](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)(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 토큰의 고정 텍스트가 들어 있습니다:

<CodeGroup>
```json title="第一次：写入缓存"
{
  "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
}
```
```json title="第二次：命中缓存"
{
  "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
}
```
</CodeGroup>

두 번째 `cache_read_input_tokens`가 0보다 크면 캐시가 읽히고 있는 것입니다. 각 호출의 캐시 쓰기/읽기 토큰은 [호출 로그](/ko/docs/usage-logs/)의 토큰 열에도 표시되며, 읽기는 "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배입니다. 이 사이트는 입력에는 할인이 있지만 캐싱에는 할인이 없으므로, 공식 배수만으로 캐시 읽기 한 번이 본전이라는 결론을 내릴 수 없습니다. 모델 할인율, 쓰기 비용, 반복 읽기 횟수를 비교해야 합니다. 전체 계산 예시는 [가격 및 과금](/ko/docs/pricing-explained/)에 있습니다.

### 1시간 캐시

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

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

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

## Claude Code의 캐싱

Claude Code는 시스템 프롬프트, 도구 정의, 대화 기록에 자동으로 캐시 브레이크포인트를 배치합니다. [공식 설명은 여기](https://code.claude.com/docs/zh-CN/prompt-caching)입니다. 히트율을 높이려면:

- 한 세션 안에서 계속 작업하세요. 중간에 오래 멈추지 마세요. 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`는 다음과 같았습니다:

```json
{"prompt_tokens": 3167, "completion_tokens": 4, "total_tokens": 3171}
```

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

## FAQ

<AccordionGroup>
<Accordion title="왜 항상 cache_creation만 있고 cache_read는 없나요?">

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

</Accordion>
<Accordion title="캐시 적중률을 볼 수 있나요?">

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

</Accordion>
</AccordionGroup>