일반적인 AI 워크플로에서는 동일한 입력 토큰을 모델에 반복해서 전달할 수 있습니다. Gemini API는 다음과 같은 두 가지 캐싱 메커니즘을 제공합니다.
암시적 캐싱 (Gemini 2.5 모델에서 자동으로 사용 설정되며 비용 절감 보장 없음)
명시적 캐싱 (대부분의 모델에서 수동으로 사용 설정 가능, 비용 절감 보장)
명시적 캐싱은 비용 절감을 보장하되 개발자 작업을 추가하려는 경우에 유용합니다.
암시적 캐싱
암시적 캐싱은 모든 Gemini 2.5 모델에 기본적으로 사용 설정됩니다. 요청이 캐시에 도달하면 비용 절감이 자동으로 전달됩니다. 이 기능을 사용 설정하기 위해 사용자가 수행해야 하는 작업은 없습니다. 이 정책은 2025년 5월 8일부터 시행됩니다. 컨텍스트 캐싱의 최소 입력 토큰 수는 2.5 Flash의 경우 1,024개, 2.5 Pro의 경우 4,096개입니다.
암시적 캐시 적중 가능성을 높이려면 다음을 따르세요.
크고 일반적인 콘텐츠를 프롬프트의 시작 부분에 배치해 보세요.
짧은 시간 내에 유사한 접두사가 있는 요청을 전송하려고 함
응답 객체의 usage_metadata 필드에서 캐시 적중된 토큰 수를 확인할 수 있습니다.
명시적 캐싱
Gemini API 명시적 캐싱 기능을 사용하면 콘텐츠를 모델에 한 번 전달하고 입력 토큰을 캐시한 다음 후속 요청에서 캐시된 토큰을 참조할 수 있습니다. 특정 볼륨에서는 캐시된 토큰을 사용하는 것이 동일한 코퍼스 토큰을 반복적으로 전달하는 것보다 비용이 저렴합니다.
토큰 집합을 캐시할 때 토큰이 자동으로 삭제되기 전에 캐시가 유지될 기간을 선택할 수 있습니다. 이 캐싱 기간을 TTL (수명)이라고 합니다. 설정하지 않으면 TTL은 기본적으로 1시간입니다. 캐싱 비용은 입력 토큰 크기와 토큰을 유지하려는 기간에 따라 달라집니다.
이 섹션에서는 빠른 시작에 표시된 대로 Gemini SDK를 설치했거나 curl이 설치되어 있고 API 키를 구성했다고 가정합니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["필요한 정보가 없음","missingTheInformationINeed","thumb-down"],["너무 복잡함/단계 수가 너무 많음","tooComplicatedTooManySteps","thumb-down"],["오래됨","outOfDate","thumb-down"],["번역 문제","translationIssue","thumb-down"],["샘플/코드 문제","samplesCodeIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-08-22(UTC)"],[],[],null,["# Context caching\n\nPython JavaScript Go REST\n\nIn a typical AI workflow, you might pass the same input tokens over and over to\na model. The Gemini API offers two different caching mechanisms:\n\n- Implicit caching (automatically enabled on Gemini 2.5 models, no cost saving guarantee)\n- Explicit caching (can be manually enabled on most models, cost saving guarantee)\n\nExplicit caching is useful in cases where you want to guarantee cost savings,\nbut with some added developer work.\n\nImplicit caching\n----------------\n\nImplicit caching is enabled by default for all Gemini 2.5 models. We automatically\npass on cost savings if your request hits caches. There is nothing you need to do\nin order to enable this. It is effective as of May 8th, 2025. The minimum input\ntoken count for context caching is 1,024 for 2.5 Flash and 4,096 for 2.5 Pro.\n\nTo increase the chance of an implicit cache hit:\n\n- Try putting large and common contents at the beginning of your prompt\n- Try to send requests with similar prefix in a short amount of time\n\nYou can see the number of tokens which were cache hits in the response object's\n`usage_metadata` field.\n\nExplicit caching\n----------------\n\nUsing the Gemini API explicit caching feature, you can pass some content\nto the model once, cache the input tokens, and then refer to the cached tokens\nfor subsequent requests. At certain volumes, using cached tokens is lower cost\nthan passing in the same corpus of tokens repeatedly.\n\nWhen you cache a set of tokens, you can choose how long you want the cache to\nexist before the tokens are automatically deleted. This caching duration is\ncalled the *time to live* (TTL). If not set, the TTL defaults to 1 hour. The\ncost for caching depends on the input token size and how long you want the\ntokens to persist.\n\nThis section assumes that you've installed a Gemini SDK (or have curl installed)\nand that you've configured an API key, as shown in the\n[quickstart](/gemini-api/docs/quickstart).\n\n### Explicit caching using the OpenAI library\n\nIf you're using an [OpenAI library](/gemini-api/docs/openai), you can enable\nexplicit caching using the `cached_content` property on\n[`extra_body`](/gemini-api/docs/openai#extra-body).\n\nWhen to use explicit caching\n----------------------------\n\nContext caching is particularly well suited to scenarios where a substantial\ninitial context is referenced repeatedly by shorter requests. Consider using\ncontext caching for use cases such as:\n\n- Chatbots with extensive [system instructions](/gemini-api/docs/system-instructions)\n- Repetitive analysis of lengthy video files\n- Recurring queries against large document sets\n- Frequent code repository analysis or bug fixing\n\n### How explicit caching reduces costs\n\nContext caching is a paid feature designed to reduce overall operational costs.\nBilling is based on the following factors:\n\n1. **Cache token count:** The number of input tokens cached, billed at a reduced rate when included in subsequent prompts.\n2. **Storage duration:** The amount of time cached tokens are stored (TTL), billed based on the TTL duration of cached token count. There are no minimum or maximum bounds on the TTL.\n3. **Other factors:** Other charges apply, such as for non-cached input tokens and output tokens.\n\nFor up-to-date pricing details, refer to the Gemini API [pricing\npage](/pricing). To learn how to count tokens, see the [Token\nguide](/gemini-api/docs/tokens).\n\n### Additional considerations\n\nKeep the following considerations in mind when using context caching:\n\n- The *minimum* input token count for context caching is 1,024 for 2.5 Flash and 2,048 for 2.5 Pro. The *maximum* is the same as the maximum for the given model. (For more on counting tokens, see the [Token guide](/gemini-api/docs/tokens)).\n- The model doesn't make any distinction between cached tokens and regular input tokens. Cached content is a prefix to the prompt.\n- There are no special rate or usage limits on context caching; the standard rate limits for `GenerateContent` apply, and token limits include cached tokens.\n- The number of cached tokens is returned in the `usage_metadata` from the create, get, and list operations of the cache service, and also in `GenerateContent` when using the cache."]]
