developers.openai.com/api/docs/guides/prompt-caching, 2026년 6월 기준)를 바탕으로 하며, 예시는 APIYI에 맞게 수정되었습니다.
한 문장 버전
요청의 시작 구간(접두사)이 최근 요청과 정확히 일치하고 길이가 최소 1024 tokens인 경우, 서버는 이를 다시 처리하지 않습니다. 일치한 부분은 **0.1×**로 과금되고 지연 시간은 최대 80%까지 줄어듭니다. Claude의 캐싱과 가장 큰 차이점은 두 가지입니다.- 마커가 없습니다:
cache_control같은 표시가 없으며, 조건이 충족되면 자동으로 캐싱이 적용됩니다 - 쓰기 요금이 없습니다: Claude는 쓰기에 1.25× / 2×를 청구하지만, OpenAI는 무료로 기록합니다
굳이 신경 써야 하는 이유 — 과금 배수
모델의 원시 input token 가격을 **1×**로 두면:
손익분기점: 두 번째 요청입니다. 상각할 쓰기 비용이 없으므로, 접두부를 재사용할 때마다 순수한 절감이 됩니다. Claude처럼 선불로 1.25×를 내고 두 번 재사용해야 손익분기점에 도달하는 것보다 단순합니다.
APIYI의 실시간 가격(1M tokens당):
적합한 경우
- 긴 시스템 prompt와 도구 정의를 여러 호출에서 재사용하는 경우(에이전트, 지원 봇)
- 여러 턴 대화(새 턴마다 이전 기록 전체에 자동으로 캐시 적중)
- 하나의 문서를 일괄 처리하는 경우(하나의 계약서에 대해 50개의 질문을 하는 경우)
- prompt 앞부분에 고정 문서 청크를 배치한 RAG
적합하지 않은 경우
- 첫 글자부터 완전히 다른 요청
- 전체가 1024 tokens 미만인 prompt(캐싱 임계값 미만)
적중을 위한 세 가지 엄격한 조건
세 가지 모두 필요합니다.1. 최소 1024 token의 접두사
1024 token보다 짧은 요청은 절대 캐시되지 않습니다(오류는 없으며, 조용히 적용되지 않을 뿐입니다). 1024를 넘으면 적중 길이는 128-token 단위로 늘어납니다. 일치한 길이는 1024, 1152, 1280 … 같은 단계에 도달하므로,cached_tokens은 보통 전체 안정 접두사보다 약간 짧게 읽힙니다. 이는 정상입니다.
2. 바이트 단위로 완전히 동일한 접두사
캐싱은 접두사 일치 방식입니다. 비교는 첫 글자에서 시작해 처음 차이가 나는 지점에서 멈춥니다. 타임스탬프, 사용자 이름, JSON 키 순서 같은 어떤 변경도 그 뒤의 모든 항목을 정가로 과금하게 만듭니다. 실용적인 규칙: 안정적인 콘텐츠를 먼저, 변동 가능한 콘텐츠는 마지막에 둡니다.3. 보존 기간 내 재사용
- 기본 보존: 유휴 상태가 5~10분 지나면 제거되며, 최대 1시간입니다
- 2026년 5월 29일(UTC)부터, gpt-5.1 및 이후 모델(Pro 변형 포함)은 ZDR이 아닌 조직에 대해 기본적으로 24시간 확장 보존(
prompt_cache_retention: "24h")을 사용하며, 추가 비용은 없습니다 — 당일 재사용은 사실상 항상 적중합니다
최소 동작 예제
같은 긴 프리픽스를 서로 다른 질문과 함께 두 번 보내십시오 — 첫 번째 쓰기는 자동이고, 두 번째는 캐시 적중입니다:cached는 시스템 prompt 길이(128로 반올림)와 가깝습니다 — 해당 부분은 10%로 과금됩니다.
/v1/responses 엔드포인트도 자동으로 캐시합니다; 필드는 usage.input_tokens_details.cached_tokens입니다. OpenAI의 내부 테스트에 따르면 Responses에서의 캐시 활용률은 Chat Completions보다 40%–80% 더 높습니다 — 멀티턴 에이전트의 경우 네이티브 호출을 선호합니다.적중했습니까? usage 필드를 읽어보세요
cached_tokens > 0는 절약을 의미합니다: 해당 부분은 0.1×로 과금되며, 나머지 prompt_tokens - cached_tokens는 정가로 과금됩니다.
고급: 적중률 높이기
prompt_cache_key 라우팅
적중하려면 요청이 동일한 캐시 머신에 도달해야 합니다. 기본 prefix-hash 라우팅이면 보통 충분하지만, 많은 사용자가 비슷한 prefix를 공유하거나 동시 실행 수가 높을 때는 명시적인prompt_cache_key가 적중률을 눈에 띄게 높입니다:
안정적인 prefix 설계
- 도구 정의 순서와 JSON 직렬화를 고정하십시오(직렬화기가 key 순서를 임의로 섞지 않도록 하십시오)
- 이미지 입력도 prefix 매칭에 포함됩니다 — 재사용할 때는 URL / base64와
detail매개변수를 동일하게 유지하십시오 - 시나리오별로 사용할 수 있는 tools를 바꾸려면
allowed_tools를 사용해 하위 집합을 제한하고tools목록은 수정하지 마십시오 — 전자는 캐시 prefix를 깨지 않습니다
다중 턴 채팅은 자동으로 적중됩니다
append-only messages 배열은 prefix 안정성을 자연스럽게 만족합니다. 각 턴의 기록은 이전 턴의 전체 prefix이기 때문입니다. 추가 작업 없이 자동으로 적중이 발생합니다.흔한 함정
한눈에 보는 OpenAI 대 Claude 캐싱
Claude 측의 전체 가이드는 Claude 캐시 과금 가이드를 참조하십시오.
APIYI와 캐싱
APIYI OpenAI 채널은 캐시 적중을 지원합니다. 요청은 그대로 상위로 전달되며,
cached_tokens 필드는 변경 없이 반환되고, 과금 대시보드에는 일치한 부분이 공식 0.1배 요율의 별도 “cache read” 항목으로 표시됩니다. 코드에서 미들웨어 전용 조정은 필요하지 않습니다.- 최소 1024 token의 안정적인 접두사를 구성하여 요청을 연달아 2번 보냅니다
- 2번째 응답에는
cached_tokens > 0가 표시되어야 합니다 - 호출 로그에서 2번째 요청의 입력 비용이 1번째보다 눈에 띄게 낮아야 합니다
핵심 요점
1. 완전 자동
마커도 없고 쓰기 요금도 없습니다 — caching은 자동으로 적용되며 두 번째 사용부터는 그대로 절감입니다.
2. 충분한 길이
caching을 시작하려면 최소 1024 tokens의 prefix가 필요합니다. hits는 128-token 단위로 계산됩니다.
3. 안정적인 prefix
안정적인 콘텐츠를 앞에 두고 변동되는 콘텐츠는 뒤에 두십시오. 시작 부분에는 타임스탬프와 랜덤 ID를 넣지 마십시오.
4. 사용량 확인
cached_tokens > 0만이 hit를 증명합니다 — 그 부분은 10%로 과금됩니다.관련 링크
- 이 그룹: 네이티브 호출 · 호환 모드 · 함수 호출
- Claude 측 캐싱: Claude 캐시 과금 안내
- token 가져오기 / 관리:
https://api.apiyi.com/token - 공식 OpenAI 문서:
developers.openai.com/api/docs/guides/prompt-caching