> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GPT 프롬프트 캐싱

> GPT 프롬프트 캐싱(Prompt Caching) 사용법과 요금: GPT-5.6 시리즈 gpt-5.6-sol / gpt-5.6-terra / gpt-5.6-luna는 캐시 쓰기 1.25배·읽기 0.1배 과금, prompt_cache_key와 명시적 캐시 중단점, 히트 문제 해결 포함.

GPT 시리즈 모델(gpt-4o 및 이후)의 프롬프트 캐싱(Prompt Caching)은 자동으로 적용됩니다. 요청 접두사가 1,024 토큰에 도달하고 최근 요청과 글자 단위로 일치하면, 히트한 부분은 캐시 읽기 가격으로 과금되며 첫 토큰 지연도 줄어듭니다. GPT-5.6 시리즈(`gpt-5.6-sol` / `gpt-5.6-terra` / `gpt-5.6-luna`)는 캐시 메커니즘을 업그레이드했습니다. 캐시 쓰기가 별도 과금되기 시작했고(입력 가격의 1.25배), 캐시 읽기는 입력 가격의 0.1배이며, 캐시는 최소 30분 유지되고, 신뢰할 수 있는 매칭을 위한 `prompt_cache_key`와 명시적 캐시 중단점 파라미터가 추가되었습니다.

두 세대 모델의 캐시 동작 요약:

|                    | GPT-5.6 이전                         | GPT-5.6 및 이후                                   |
| :----------------- | :--------------------------------- | :--------------------------------------------- |
| 캐시 방식              | 자동                                 | 자동 + 명시적 중단점                                   |
| 최소 캐시 길이           | 1,024 토큰                           | 1,024 토큰                                       |
| 캐시 쓰기 과금           | 별도 과금 없음                           | 기본 입력 가격의 1.25배                                |
| 캐시 읽기 과금           | 해당 모델의 캐시 읽기 가격                    | 기본 입력 가격의 0.1배                                 |
| 캐시 유지 시간           | 비활성 5–10분 후 삭제, 최대 1시간             | 최소 30분 유지                                      |
| `prompt_cache_key` | 선택 사항, 히트율 향상용                     | 더 신뢰할 수 있는 캐시 매칭을 위해 공식적으로 설정 요구               |
| 24시간 확장 유지         | 일부 모델 지원(`prompt_cache_retention`) | `prompt_cache_options.ttl`로 대체, 현재 `"30m"`만 지원 |

## 빠른 시작

프롬프트 캐싱은 추가 구성이 필요 없습니다. 동일한 긴 접두사로 두 번 연속 요청하고, 두 번째 응답의 `usage.prompt_tokens_details.cached_tokens`가 0보다 크면 히트입니다. GPT-5.6 시리즈는 `prompt_cache_key`도 함께 설정하는 것이 좋습니다:

<CodeGroup>
  ```shell Curl theme={null}
  curl https://aihubmix.com/v1/chat/completions \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -d '{
      "model": "gpt-5.6-sol",
      "prompt_cache_key": "my-app-report-assistant-v1",
      "messages": [
        {
          "role": "system",
          "content": "You are a meticulous assistant for analyzing quarterly financial reports... [변하지 않는 긴 지침 또는 참고 자료를 여기에 배치, ≥1024 토큰]"
        },
        {
          "role": "user",
          "content": "Summarize the key figures in one sentence."
        }
      ]
    }'
  ```

  ```py Python (OpenAI SDK) theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["AIHUBMIX_API_KEY"],  # 키는 환경 변수에서 읽습니다
      base_url="https://aihubmix.com/v1",
  )

  long_context = "You are a meticulous assistant for analyzing quarterly financial reports... [변하지 않는 긴 지침 또는 참고 자료, ≥1024 토큰]"

  # 동일한 접두사로 두 번 연속 요청하면 두 번째에 캐시에 히트합니다
  for i in range(2):
      completion = client.chat.completions.create(
          model="gpt-5.6-sol",
          prompt_cache_key="my-app-report-assistant-v1",
          messages=[
              {"role": "system", "content": long_context},
              {"role": "user", "content": "Summarize the key figures in one sentence."},
          ],
      )
      print(completion.usage.prompt_tokens_details)
  ```
</CodeGroup>

두 호출의 실측 usage(2026-07-10, `gpt-5.6-sol`):

```json theme={null}
// 1번째 호출: 미히트
"prompt_tokens_details": {"audio_tokens": 0, "cached_tokens": 0}

// 2번째 호출: 접두사가 캐시에 히트
"prompt_tokens_details": {"audio_tokens": 0, "cached_tokens": 2816}
```

## 캐시 요금

GPT-5.6 시리즈의 캐시 과금 규칙:

| 과금 항목    | 요율              |
| :------- | :-------------- |
| 일반 입력 토큰 | 플랫폼 요금          |
| 캐시 쓰기 토큰 | 기본 입력 가격의 1.25배 |
| 캐시 읽기 토큰 | 기본 입력 가격의 0.1배  |
| 출력 토큰    | 플랫폼 요금          |

이 규칙에 대한 OpenAI 공식 설명([GPT-5.6 발표 공지](https://openai.com/index/gpt-5-6/)): "For GPT‑5.6 and later models, cache writes are billed at 1.25x the model's uncached input rate, while cache reads continue to receive the 90% cached-input discount." [공식 프롬프트 캐싱 가이드](https://developers.openai.com/api/docs/guides/prompt-caching)에서 이 요율의 적용 범위는 "GPT-5.6 models and later model families"(GPT-5.6 및 이후 모델 패밀리)로 표현되어 있습니다. 각 모델의 공식 가격은 [OpenAI Pricing](https://developers.openai.com/api/docs/pricing)을, AIHubMix 실제 가격은 [모델 광장](https://aihubmix.com/models)을 참고하세요.

공식 요율로 손익을 직접 계산할 수 있습니다. 접두사를 한 번 캐시에 쓰면 캐싱하지 않을 때보다 입력 가격의 0.25배를 더 내고, 이후 히트할 때마다 입력 가격의 0.9배를 절약합니다. 접두사가 1번만 재사용되어도 순절감이 되며, 재사용 횟수가 많을수록 절감액이 커집니다. 접두사가 전혀 재사용되지 않는 일회성 요청은 쓰기 비용을 추가로 내게 되므로, explicit 모드로 캐싱을 끌 수 있습니다(아래 「GPT-5.6 캐시 파라미터」 참고).

GPT-5.6 이전 모델은 캐시 쓰기에 별도 요금이 없고, 캐시 읽기는 해당 모델의 캐시 읽기 가격으로 과금됩니다. 각 모델 가격은 [모델 광장](https://aihubmix.com/models)을 참고하세요.

<Note>
  GPT-5.6 시리즈는 롱 컨텍스트 요금 구간을 구분합니다. 단일 요청 입력이 272K 토큰을 초과하면 요청 전체가 롱 컨텍스트 구간으로 과금됩니다(입력 2배, 출력 1.5배). 캐시 쓰기 1.25배·읽기 0.1배 요율은 롱 컨텍스트 구간에서도 동일하게 적용되며, 기준은 롱 컨텍스트 구간의 입력 가격입니다.
</Note>

## 캐시가 자동으로 적용되는 방식

요청을 보내면 시스템이 요청 접두사(messages, tools 등을 직렬화한 순서 기준)가 최근 요청의 접두사와 글자 단위로 일치하는지 확인합니다:

1. 접두사가 1,024 토큰에 도달하고 일치하는 캐시 접두사가 있으면, 히트한 부분은 캐시 읽기 가격으로 과금되고 첫 토큰 지연이 줄어듭니다.
2. 없으면 일반 입력으로 처리하고 접두사를 캐시에 기록합니다(GPT-5.6 및 이후는 1.25배 쓰기 비용 과금).
3. 히트하려면 접두사가 바이트 단위로 일치해야 하며, 접두사 중 한 곳이라도 바뀌면 그 위치 이후의 캐시가 모두 무효화됩니다.

다음 시나리오에서 효과가 가장 큽니다:

* 고정된 긴 시스템 지침 또는 대량의 few-shot 예시
* 긴 참고 자료를 반복 인용하는 RAG 시나리오
* 대량의 도구 정의(tools)를 포함하는 Agent 워크플로
* 메시지를 뒤로만 추가하는 긴 다중 턴 대화

캐시 유지 시간: GPT-5.6 이전 모델은 비활성 5–10분 후 삭제되며 최대 1시간입니다. GPT-5.6 및 이후는 최소 30분 유지되며 실제로는 더 오래 유지될 수 있습니다. 캐시는 조직 간에 공유되지 않으며, 캐시는 출력 내용에 영향을 주지 않습니다.

## GPT-5.6 캐시 파라미터

GPT-5.6 시리즈에는 캐시 관련 파라미터 3개가 추가되었습니다(Chat Completions와 Responses API 공통):

| 파라미터                      | 타입 / 위치           | 값                                                                 | 기본값                              |
| :------------------------ | :---------------- | :---------------------------------------------------------------- | :------------------------------- |
| `prompt_cache_key`        | string, 요청 본문 최상위 | 사용자 정의 고정 식별자. 비즈니스 또는 테넌트 단위 분할 권장, key 하나당 총 트래픽은 약 15회/분 이내 권장 | 없음                               |
| `prompt_cache_options`    | object, 요청 본문 최상위 | `mode`: `"implicit"` / `"explicit"`; `ttl`: `"30m"`만 지원           | `mode: "implicit"`, `ttl: "30m"` |
| `prompt_cache_breakpoint` | object, 콘텐츠 블록 내  | `{"mode": "explicit"}`, 캐시 접두사의 끝 위치 표시                           | 중단점 미설정                          |

GPT-5.6 이전 모델은 이 세 파라미터 중 `prompt_cache_options`와 `prompt_cache_breakpoint`를 지원하지 않으며 요청이 거부됩니다. 구형 모델의 24시간 확장 유지 파라미터 `prompt_cache_retention`(`"24h"` / `"in_memory"`)은 GPT-5.6 및 이후에서 `prompt_cache_options.ttl`로 대체되었습니다.

세 가지 캐시 제어 방식의 관계:

1. **기본(implicit 모드)**: 캐시 파라미터를 전혀 전달하지 않아도 자동으로 캐시에 기록됩니다. 시스템이 최신 메시지 위치에 자동으로 중단점을 설정합니다. GPT-5.6 및 이후에서는 자동으로 발생한 캐시 쓰기도 1.25배로 과금됩니다.
2. **implicit 모드 + 명시적 중단점**: 자동 중단점 외에 콘텐츠 블록에 `prompt_cache_breakpoint`를 설정하여 캐시 경계를 고정 콘텐츠의 끝에 고정할 수 있습니다. 중단점 이후의 콘텐츠 변경은 중단점 이전의 접두사 캐시를 깨뜨리지 않습니다.
3. **explicit 모드**: `prompt_cache_options.mode`를 `"explicit"`으로 설정하면 수동 중단점만 사용합니다. 중단점을 전혀 설정하지 않으면 해당 요청은 캐시를 사용하지 않고 캐시 쓰기 비용도 발생하지 않습니다. [공식 원문](https://developers.openai.com/api/docs/guides/prompt-caching): "If the conversation contains no explicit breakpoints, the request does not use prompt caching or incur cache-write charges."

explicit 모드로 일회성 긴 요청의 캐시 쓰기 비용 끄기:

```json theme={null}
{
  "model": "gpt-5.6-sol",
  "prompt_cache_options": {"mode": "explicit"},
  "messages": [
    {"role": "user", "content": "[재사용되지 않는 일회성 긴 콘텐츠]"}
  ]
}
```

명시적 중단점의 공식 표준 용법(고정된 긴 콘텐츠 블록의 끝에 중단점 설정):

```json theme={null}
{
  "model": "gpt-5.6-sol",
  "prompt_cache_key": "my-app-report-assistant-v1",
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "[변하지 않는 긴 지침 또는 참고 자료, ≥1024 토큰]",
          "prompt_cache_breakpoint": {"mode": "explicit"}
        }
      ]
    },
    {"role": "user", "content": "Summarize the key figures in one sentence."}
  ]
}
```

하드 제약(공식 기준):

* 요청당 최대 4개의 새 캐시 쓰기를 생성할 수 있으며, implicit 모드의 자동 중단점이 그중 1개를 차지합니다.
* 중단점 이전의 접두사가 1,024 토큰에 도달해야 캐시에 기록됩니다.
* 읽기 시 최근 50개 중단점 중 가장 긴 일치 접두사를 사용합니다.
* 지원되지 않는 콘텐츠 블록에 중단점을 설정하면 `400 invalid_request_error`가 반환됩니다. Chat Completions는 `text` / `image_url` / `input_audio` / `file` / `refusal` 블록을, Responses API는 `input_text` / `input_image` / `input_file` 블록을 지원합니다.

<Note>
  AIHubMix의 `prompt_cache_breakpoint` 콘텐츠 블록 중단점 및 Responses API 캐시 히트 지원은 보완 중입니다. 현재는 Chat Completions로 자동 캐싱을 사용하면서 `prompt_cache_key`를 설정하는 방식을 권장합니다(본 페이지 빠른 시작 예시, 히트 검증 완료). `prompt_cache_options`의 explicit 모드는 캐시 쓰기를 끄는 용도로 정상 사용할 수 있습니다. 본 페이지는 지원 진행에 따라 업데이트됩니다.
</Note>

## 캐시가 히트하지 않는 이유

히트하려면 중단점 위치 이전의 모든 콘텐츠가 바이트 단위로 일치해야 합니다. 두 번째 요청에서 `cached_tokens`가 여전히 0이면 다음 체크리스트로 확인하세요:

* **접두사가 1,024 토큰 미만**: 최소 캐시 길이 미만의 요청은 일반 입력으로 처리됩니다.
* **접두사에 변하는 콘텐츠가 섞임**: 타임스탬프, 세션 ID, 사용자 변수 등은 고정 콘텐츠 뒤에 배치해야 합니다. 접두사 중 한 곳이라도 바뀌면 그 이후의 캐시가 무효화됩니다.
* **tools 정의 또는 순서 변경**: 도구 목록은 접두사 계산에 포함되며, 정의와 배열 순서가 완전히 일치해야 합니다.
* **이미지 detail 파라미터 불일치**: `detail`은 이미지 토큰화 결과에 영향을 주므로 동일하게 유지해야 합니다.
* **구조화된 출력 schema 변경**: `response_format`의 JSON Schema는 시스템 메시지 접두사로 캐시에 포함되며, schema가 바뀌면 접두사도 바뀝니다.
* **`reasoning_effort` 변경**: 공식 문서에서 캐시 적중률 저하의 일반적인 원인으로 명시되어 있습니다("Changes to reasoning effort").
* **캐시 유지 기간 초과**: GPT-5.6 이전은 비활성 5–10분 후 삭제되고, GPT-5.6 및 이후는 최소 30분 유지됩니다.
* **`prompt_cache_key` 미설정(GPT-5.6)**: 설정하지 않아도 자동으로 히트할 수 있으나, 더 신뢰할 수 있는 매칭 메커니즘을 사용하지 않게 됩니다.

## 모범 사례

* 고정 콘텐츠(시스템 지침, 예시, 참고 자료, 도구 정의)는 요청의 맨 앞에, 매 턴 바뀌는 콘텐츠는 맨 뒤에 배치하세요.
* 동일한 접두사를 공유하는 트래픽에는 동일한 고정 `prompt_cache_key`를 설정하고, key 하나당 총 트래픽은 약 15회/분 이내로 유지하세요. 초과 시 비즈니스 단위로 key를 더 분할하세요.
* 다중 턴 대화는 메시지를 뒤로만 추가하고, 과거 메시지를 수정하지 마세요.
* 동일 접두사 요청에 지속적인 트래픽을 유지하여 캐시 삭제를 줄이세요.
* 접두사가 재사용되지 않는 일회성 긴 요청은 explicit 모드로 캐시 쓰기 비용을 피하세요(GPT-5.6 및 이후).
* `usage.prompt_tokens_details.cached_tokens`로 히트 상황을 지속적으로 모니터링하세요.

## 자주 묻는 질문(FAQ)

### GPT 프롬프트 캐싱은 수동으로 켜야 하나요?

수동으로 켤 필요가 없습니다. 접두사가 1,024 토큰에 도달하면 자동으로 캐시됩니다. GPT-5.6 및 이후에서는 더 신뢰할 수 있는 캐시 매칭을 위해 `prompt_cache_key`도 함께 설정하는 것이 좋습니다.

### GPT-5.6의 캐시 쓰기 비용은 어떻게 계산되나요? 불필요한 쓰기 비용은 어떻게 피하나요?

캐시 쓰기는 기본 입력 가격의 1.25배, 읽기는 0.1배로 과금됩니다. 접두사가 1번만 재사용되어도 순절감이 됩니다. 접두사가 재사용되지 않는 일회성 긴 요청은 `prompt_cache_options.mode`를 `"explicit"`으로 설정하고 중단점을 설정하지 않으면, 해당 요청은 캐시를 사용하지 않고 쓰기 비용도 발생하지 않습니다.

### 캐시는 얼마나 유지되나요?

GPT-5.6 및 이후는 최소 30분 유지됩니다(`ttl`은 현재 `"30m"`만 지원하며 실제로는 더 오래 유지될 수 있습니다). GPT-5.6 이전 모델은 비활성 5–10분 후 삭제되고 최대 1시간이며, 일부 구형 모델은 `prompt_cache_retention: "24h"` 확장 유지를 지원합니다.

### GPT-5.6의 명시적 중단점과 Claude의 cache\_control은 무엇이 다른가요?

둘 다 캐시 경계를 고정 콘텐츠의 끝에 고정하는 데 사용됩니다. 주요 차이: GPT-5.6은 파라미터 없이 자동으로 캐시되며 중단점은 선택적 세밀 제어입니다. Claude는 요청에서 캐싱을 활성화해야 합니다(최상위 `cache_control` 자동 중단점 또는 콘텐츠 블록 단위 명시적 중단점). GPT-5.6 캐시는 최소 30분 유지되고, Claude는 기본 5분에 선택적으로 1시간입니다. 두 모델 모두 캐시 읽기는 입력 가격의 0.1배로 과금됩니다. Claude의 용법은 [Claude 프롬프트 캐싱](/ko/api/Claude-Cache)을 참고하세요.

### 캐시가 출력 내용에 영향을 주나요?

영향이 없습니다. 공식 기준: 프롬프트 캐싱은 입력 측의 처리와 과금에만 영향을 주며, 모델이 출력을 생성하는 방식은 캐시를 사용하지 않을 때와 완전히 동일합니다.

## 공식 참고 자료

본 페이지의 메커니즘, 요율, 파라미터 기준은 모두 다음 OpenAI 공식 출처에서 가져왔습니다:

* [GPT-5.6 발표 공지](https://openai.com/index/gpt-5-6/): 캐시 쓰기 1.25배 / 읽기 90% 할인 과금 규칙
* [프롬프트 캐싱 가이드](https://developers.openai.com/api/docs/guides/prompt-caching): 메커니즘, 파라미터, usage 필드와 제한
* [OpenAI Pricing](https://developers.openai.com/api/docs/pricing): 각 모델 공식 가격
* [GPT-5.6 모델 문서](https://platform.openai.com/docs/models/gpt-5.6-sol): 컨텍스트 윈도우, 롱 컨텍스트 과금 임계값

AIHubMix 각 모델의 실제 가격은 [모델 광장](https://aihubmix.com/models)을 참고하세요.

***

마지막 업데이트: 2026-07-10