BizRouter 비즈라우터

프롬프트 캐싱

반복되는 프롬프트 앞부분을 캐시해 비용과 지연을 줄이는 방법입니다. 모델 계열마다 캐시를 켜는 방법과 적중 조건이 다르므로, 같은 요청 모양이어도 한 계열에서는 적중하고 다른 계열에서는 적중하지 않을 수 있습니다. 아래 예시와 파라미터는 Chat Completions API 기준이며, Responses API와 Messages API에서의 차이는 각 API 문서에 있습니다.

모델 계열별 방법

계열에 맞는 방법을 쓰지 않으면 캐시가 적용되지 않거나, 읽기 없이 쓰기 요금만 나올 수 있습니다 모델 계열 켜는 방법 단가(입력 대비) 적중 확인 단가 배율은 2026년 11월 16일 기준이며 프로바이더 정책에 따라 바뀔 수 있습니다. 정확한 단가는 모델별 요금 정책을 따릅니다.

Claude (cache_control)

Claude 계열 모델은 이 엔드포인트에서도 Anthropic 방식의 cache_control 마커를 그대로 지원합니다. 반복되는 시스템 프롬프트나 대화 프리픽스가 큰 에이전트형 워크로드에서 입력 비용을 크게 절감할 수 있습니다. Messages API 와 동일한 마커 전략이 동일하게 동작합니다.

마커 위치

다음 세 위치의 cache_control: {"type": "ephemeral"} 마커를 모두 수용합니다: 콘텐츠 파트 레벨 — 배열형 content의 개별 파트에 지정 메시지 레벨 — 메시지 객체에 직접 지정 (마지막 콘텐츠 블록에 적용) Tool 레벨 — tools 배열의 개별 tool 정의에 지정

usage 보고

캐싱이 적용된 요청의 usage는 OpenAI 규약을 따릅니다. prompt_tokens 는 캐시 read/write를 포함한 전체 입력 토큰이며, 캐시에서 읽은 토큰 수는 prompt_tokens_details.cached_tokens 로 제공됩니다. 스트리밍에서는 마지막 usage 청크에 같은 필드가 담깁니다: 캐시 토큰 과금 캐시 read 토큰( cache_read_input_tokens )과 캐시 write 토큰( cache_creation_input_tokens )은 일반 입력 토큰과 다른 단가로 과금됩니다. 실제 단가는 모델별 요금 정책을 따르며, Anthropic 기준으로 캐시 read는 대략 입력 단가의 0.1배, 캐시 write는 대략 1.25배 수준입니다(2026년 7월 3일 기준, 프로바이더 정책에 따라 변동될 수 있음). 캐시 히트가 반복되는 워크로드에서는 입력 비용이 크게 절감됩니다.

OpenAI GPT-5.6 이후 (prompt_cache_breakpoint)

기본 설정은 요청의 마지막 메시지 끝에만 캐시를 저장합니다 GPT-5.6 이후 OpenAI 모델(예: openai/gpt-5.6-sol , openai/gpt-6.1-sol )은 cache_control 을 쓰지 않습니다. 1,024 토큰 이상의 입력에 제공사의 캐시가 적용되며, 캐시 읽기와 쓰기 토큰 수가 그대로 전달됩니다. 캐시 방식은 prompt_cache_options.mode 로 고릅니다. 방식 설정 캐시에 저장되는 곳 쓰기 청구 기본 prompt_cache_options 생략 또는 {"mode": "implicit"} 요청의 마지막 메시지 끝(표시한 곳이 있으면 그곳도) 저장한 토큰 전체 명시 {"mode": "explicit"} + prompt_cache_breakpoint 표시 표시한 블록의 끝까지 표시한 부분만(표시가 없으면 캐시도, 쓰기 청구도 없음) 고정 지시문 뒤에 매번 다른 내용이 붙는 요청 기본 방식은 마지막 메시지 끝에만 저장하므로, 앞의 지시문이 같아도 뒤의 내용이 달라지면 저장된 지점이 매번 달라져 읽기가 0이 됩니다. 이때 요청 전체가 캐시 쓰기로 처리되어 입력 요금이 캐시를 쓰지 않을 때보다 약 25% 늘어납니다. 응답의 prompt_tokens_details.cache_write_tokens 가 매 호출 0보다 크면 이 경우입니다. BizRouter 측정(2026-11-16, openai/gpt-5.6-sol , 고정 지시문 약 3,400 토큰 뒤에 매번 다른 내용을 붙인 요청 3회): 기본 방식은 3회 모두 cached_tokens 0에 cache_write_tokens 약 3,780이었습니다. 명시 방식은 첫 호출이 지시문 부분만 3,380 토큰 쓰고, 둘째와 셋째 호출이 3,380 토큰을 읽었으며 호출당 요금이 약 80% 줄었습니다.

GPT 요청 예시

지시문의 마지막 블록에 표시하고, 요청에 명시 방식을 켭니다

GPT usage 확인

읽은 토큰과 쓴 토큰이 따로 표시됩니다 prompt_tokens 는 읽은 토큰과 쓴 토큰을 포함한 전체 입력입니다. 입력 토큰 하나는 일반 입력, 캐시 읽기, 캐시 쓰기 중 하나의 단가로만 청구됩니다. 새 지시문으로 처음 호출할 때는 읽기 0에 쓰기가 찍히는 것이 정상이며, 같은 지시문으로 다시 호출하면 읽기로 바뀝니다.

GPT 캐시 사용 시 유의할 점

표시 앞의 내용이 한 글자라도 바뀌거나 호출마다 tools , reasoning_effort , 응답 형식을 바꾸면 캐시가 맞지 않아 새로 씁니다(제공사 안내). 캐시 유지 시간은 제공사 기본값으로 약 30분입니다. 호출 간격이 그보다 길면 다시 씁니다. prompt_cache_key 는 선택 값입니다. 이 모델들은 같은 캐시로 이어 주는 일을 제공사가 자동으로 하므로 적중에 필요하지 않고, 사용자나 고객별로 캐시를 구분하고 싶을 때 씁니다. 읽기 단가는 입력의 0.1배(GPT-6.1 Sol·Terra는 0.05배), 쓰기 단가는 1.25배입니다(2026년 11월 16일 기준, 프로바이더 정책에 따라 변동될 수 있음). Messages API에서의 같은 필드는 Messages API 문서에 있습니다.

Google Gemini

자동 캐시만 제공하며, 적중했을 때만 cached_tokens가 응답에 나타납니다 Gemini는 따로 켜는 설정이 없습니다. 제공사가 캐시를 적용한 요청에만 캐시 토큰 수를 알려 주므로, 적중하지 않은 응답에는 prompt_tokens_details 자체가 없습니다. 오류가 아니라 이번 호출에 캐시가 적용되지 않았다는 뜻입니다. 읽은 토큰은 입력보다 낮은 캐시 읽기 단가로 청구되며, google/gemini-3.8-flash 는 입력 단가의 10%입니다. 적중 조건은 제공사가 정하며 모델 세대마다 다릅니다. BizRouter 측정(2026-11-16, google/gemini-3.8-flash , 입력 약 19,000~20,000 토큰, 각 3회)에서는 요청 본문이 완전히 같을 때 둘째 호출부터 입력의 약 89%(17,198 / 19,250 토큰)가 읽혔고, 지시문만 같고 뒤의 내용이 다른 요청은 3회 모두 적중하지 않았습니다. 같은 지시문 뒤에 매번 다른 내용을 붙이는 요청은 Gemini의 자동 캐시에 기대지 말고, 응답의 cached_tokens 로 직접 확인하십시오. Gemini의 명시적 캐시(cachedContents)는 BizRouter에서 제공하지 않습니다.

그 밖의 모델

제공사의 자동 캐시를 따릅니다 위에 없는 모델은 제공사의 자동 캐시를 따릅니다. 별도 설정이 없고, 캐시가 적용되면 usage에 같은 필드( prompt_tokens_details.cached_tokens )로 표시됩니다. 적중 조건은 제공사마다 다르므로 모델을 바꿀 때는 응답의 cached_tokens 로 적중 여부를 확인하십시오.

Claude cache_control 마커 읽기 약 0.1배 · 쓰기 약 1.25배 cached_tokens, cache_creation_input_tokens OpenAI GPT-5.6 이후 prompt_cache_options + prompt_cache_breakpoint 읽기 0.1배(GPT-6.1 Sol·Terra는 0.05배) · 쓰기 1.25배 cached_tokens, cache_write_tokens Google Gemini 설정 없음(자동 캐시만 제공) 읽기만 있음(gemini-3.8-flash는 0.1배) 적중했을 때만 cached_tokens 그 밖의 모델 제공사의 자동 캐시 모델별 요금 정책 적중했을 때 cached_tokens

주식회사 AI3 | 서울 강남구 영동대로85길 34 | support@bizrouter.ai