Skip to main content
APIYI의 Gemini 채널은 암묵적 컨텍스트 캐싱을 자동으로 활성화합니다. 요청 접두사가 적중하면 일치한 부분은 공식 할인율로 과금되며 cached_content_token_count 필드는 변경되지 않은 채 반환됩니다. 코드 변경은 전혀 없습니다. 핵심부터 말하면: Gemini 캐싱은 존재하지만, 의존해서는 안 됩니다. 암묵적 캐시 동작은 상위에서 제어되며, 실제 적중률은 OpenAI와 Claude보다 분명히 낮습니다. 이를 있으면 좋은 보너스로 여기고, 비캐시 가격으로 항상 비용을 추정하십시오. 이 페이지는 Google의 공식 문서(ai.google.dev/gemini-api/docs/caching, 2026년 6월 기준)를 바탕으로 작성되었습니다.

​
한 문장으로 보는 작동 방식

요청의 시작 구간(접두사)이 최근 요청과 일치하고 최소 길이를 충족하면, 상위 서비스가 자동으로 캐시를 재사용합니다: 일치한 부분은 공식 할인율로 과금되며(공식적으로 최대 90% 할인), 별도의 표시가 필요하지 않습니다.

​
트리거 조건

참고로 Gemini의 캐싱 임계값(4096)은 OpenAI의 1024보다 훨씬 높습니다. 따라서 짧은 system prompt는 Gemini에서 사실상 절대 적중하지 않으며, 이것이 Gemini 캐싱이 기대에 못 미치는 느낌을 주는 이유 중 하나입니다.

​
캐시 적중 확인 방법

usage_metadata.cached_content_token_count를 확인합니다:
적중은 과금 대시보드에서 할인된 항목으로 표시되며, REST 응답에서는 필드가 usageMetadata.cachedContentTokenCount입니다.

​
적중률 높이기

운용 방식은 OpenAI의 것과 동일합니다(자세한 설명은 OpenAI 캐시 과금 가이드에서 확인할 수 있습니다):
  • 안정적인 콘텐츠를 먼저 배치합니다: 긴 시스템 지침, 문서, few-shot 예시를 앞부분에 두고 사용자 입력과 타임스탬프는 뒤에 둡니다
  • 프리픽스를 길게 만듭니다: 4096 tokens 미만은( Gemini 3 시리즈) 절대 적중하지 않습니다
  • 재사용을 시간적으로 묶습니다: 배치 작업은 연달아 보내고, 간격을 너무 벌리지 않습니다
  • 멀티턴 채팅은 본질적으로 추가만 되는 프리픽스이므로 더 쉽게 적중합니다
모든 것을 올바르게 해도 적중이 보장되지는 않습니다 — 암시적 캐싱은 OpenAI/Claude의 결정적 동작과 달리 최선 노력 방식입니다.

​
명시적 캐싱 (cachedContents)

Google은 명시적 캐싱 API도 제공합니다(cachedContents — TTL이 적용된 캐시 객체를 생성하고 이를 참조합니다). 이는 상태 저장형 서버 측 리소스이며 현재 APIYI 채널에서는 지원되지 않으므로 암시적 캐싱을 사용하십시오.

​
다른 채널과의 비교

긴 선행 프리픽스가 자주 반복되는 캐시 민감 워크로드(agents, RAG, batch documents)에는 OpenAI 또는 Claude 채널을 권장합니다. 플랫폼 전체의 캐시 지원 개요는 Cache Billing FAQ를 참고하십시오.

​
관련 링크