Gemini API Context Caching: A Cost-Effective Setup to Cut Token Costs by 90%

When using AI to analyze long documents or entire source code repositories, API costs often skyrocket, which can be quite burdensome. This happens because you're forced to re-send tens of thousands of tokens of background data every single time you ask a question. By utilizing 'Context Caching' in the Gemini API, you can slash those wasted input token costs by up to 90% and significantly boost your response speeds.

How does context caching work?

In simple terms, context caching is like 'leaving a thick reference book open on your desk.' Normally, you would have to hand over a massive manual or an entire codebase to the AI with every single prompt. This structure wasted both time and money, as the same data had to be re-sent from scratch every time you tweaked your question.

Google's context caching is a technology that allows you to keep that heavy reference material open on Google's servers just once and refer to it instantly whenever needed. This dramatically speeds up response times since you no longer need to transmit the same data over and over.

This caching technology comes in two main forms: 'implicit caching,' which works automatically in Gemini 2.5 and newer models, and 'explicit caching,' where developers generate and control the lifespan of the cache via code. In this article, we will focus on explicit caching, which guarantees clear token discounts to protect your wallet.

How many tokens are required? A new cost-calculation method to save your wallet

Back in the Gemini 1.5 era, you needed a minimum of 32,768 tokens to use caching. For small toy projects or indie developers, it was effectively out of reach. However, with the release of newer models, this threshold has been drastically lowered.

Now, you can apply context caching with as little as 2,048 tokens for the Gemini 2.5 family and 4,096 tokens for the Gemini 3 and 3.5 families. This means you can reap the benefits of cost-efficiency even with just a few long articles or source code files.

The cost structure is also very reasonable. When reading data back from the cached region, the input token cost is discounted by 90%, meaning you only pay 10% of the original price. In exchange, you pay a very small hourly storage fee while the data remains on the server.

Storage costs vary based on the model class. For light and fast Flash models, the charge is $1.00 per million tokens per hour, while high-performance Pro models cost $4.50 per million tokens per hour. For customer support chatbots or code analysis tools that run for several hours, paying a few dollars in storage fees can save you hundreds of dollars in redundant input costs.

Apply caching in just 1 minute with code

Applying explicit caching is surprisingly simple. By using Google's latest official SDK, @google/genai , you can cache large volumes of data on Google's servers and reuse it whenever needed with just a few lines of code.

First, specify the background knowledge or large documents you want to keep 'open' on Google's servers and call ai.caches.create(). You can define the Time-to-Live (TTL) for how long the cache should persist; if not specified, it defaults to 1 hour. Once the cache registration is complete, you will receive a unique cache identifier called cache.name.

When sending subsequent questions, you just need to include the newly issued identifier in the cachedContent setting, and that's it.

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI();

// 1. 대용량 문서나 배경 데이터를 캐시로 등록합니다.
const cache = await ai.caches.create({
  model: 'gemini-2.5-flash',
  config: {
    displayName: 'large-doc-cache',
    ttl: '3600s', // 캐시 생존 시간 (기본값 1시간)
  },
  contents: [
    {
      role: 'user',
      parts: [{ text: '여기에 분석할 수만 글자의 대용량 소스 코드나 매뉴얼을 넣습니다.' }]
    }
  ]
});

// 2. 등록한 캐시를 지정하여 빠르게 질문을 보냅니다.
const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: '위 소스 코드에서 개선할 점을 세 가지만 찾아줘.',
  config: {
    // 생성된 캐시 이름을 지정해 재사용합니다.
    cachedContent: cache.name,
  }
});

console.log(response.text);

There is one common mistake to watch out for in practice. When sending a query that uses caching, you must not duplicate the system instructions (systemInstruction) or tool settings (tools) in the request body again.

These settings are saved when the cache is first created and are inherited automatically. To ensure everything runs cleanly without errors, leave these parts empty in your query and pass only your actual question.

Should I introduce this to my project right away?

Are you building a service where users have multiple conversations based on the same large document, long source code, or a heavy prompt? If so, Gemini's context caching will be a reliable ally for your wallet. With just a few lines of code, you can save up to 90% of the input token costs that were otherwise being wasted.

Of course, if you are running a simple chatbot that only occasionally handles light queries, you don't really need to configure caching. In fact, you might end up paying more in storage fees. However, if your service frequently hits the 2,048 or 4,096 token mark, turn on this cost-effective option from Google now and protect your wallet intelligently!