Guia de uso do cache de contexto do Gemini

Este guia explica como criar e reutilizar o cache de contexto do Gemini (Context Cache) por meio da API Chat Completions compatível com a OpenAI ou da API nativa do Gemini. Antes de começar:

export API_KEY="SUA_CHAVE_DE_API"

Os exemplos deste guia usam o gemini-3.6-flash. Para saber se outros modelos são compatíveis com Context Cache, consulte a descrição do modelo e a página de preços da plataforma.

Casos de uso

Quando várias solicitações incluem repetidamente o mesmo bloco grande de conteúdo, você pode armazenar em cache um prefixo estável, por exemplo:

Um system prompt muito longo
Uma base de conhecimento fixa ou documentação de produto
Mensagens de histórico estáveis em uma conversa com vários turnos
Definições e instruções de ferramentas que são reutilizadas

O Context Cache é adequado para solicitações em que “o conteúdo inicial permanece o mesmo e apenas a pergunta final muda”.

Uso básico

Adicione cache_control ao bloco de conteúdo da última mensagem do prefixo estável:

{
  "type": "text",
  "text": "Este é o último trecho de conteúdo do prefixo estável",
  "cache_control": {
    "type": "ephemeral",
    "ttl": "5m"
  }
}

TTLs compatíveis:

TTL	Significado
`5m`	Cache por 5 minutos
`1h`	Cache por 1 hora

Se ttl for omitido, o valor padrão será 5m.

Estrutura das mensagens

Recomendamos usar a seguinte estrutura:

system
→ Texto longo estável ou mensagens de histórico
→ Limite do prefixo estável com cache_control
→ Pergunta atual do usuário (não armazenada em cache)

A mensagem que contém cache_control e todas as mensagens anteriores formam o prefixo armazenado em cache. Deve haver pelo menos uma mensagem em tempo real depois dela.

Exemplo de solicitação compatível com a OpenAI

curl "https://api.apimart.ai/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.6-flash",
    "stream": false,
    "messages": [
      {
        "role": "system",
        "content": "Responda estritamente de acordo com o material de referência fornecido."
      },
      {
        "role": "user",
        "content": "Insira aqui o material de referência extenso que será reutilizado…"
      },
      {
        "role": "assistant",
        "content": [
          {
            "type": "text",
            "text": "Li e compreendi o material de referência acima.",
            "cache_control": {
              "type": "ephemeral",
              "ttl": "5m"
            }
          }
        ]
      },
      {
        "role": "user",
        "content": "Resuma os três principais pontos do material de referência."
      }
    ]
  }'

Na primeira vez que você enviar a solicitação, o sistema tentará criar um cache e o usará para concluir a solicitação atual.

Não é necessário chamar um endpoint separado para criar o cache. cache_control define tanto o “limite do cache” quanto o seu “período de validade”.

Exemplo de solicitação nativa do Gemini

O endpoint nativo generateContent do Gemini também permite adicionar cache_control em contents[].parts[]:

curl "https://api.apimart.ai/v1beta/models/gemini-3.6-flash:generateContent" \
  -H "x-goog-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "systemInstruction": {
      "parts": [
        {
          "text": "Responda estritamente de acordo com o material de referência fornecido."
        }
      ]
    },
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "Insira aqui o material de referência extenso que será reutilizado…"
          }
        ]
      },
      {
        "role": "model",
        "parts": [
          {
            "text": "Li e compreendi o material de referência acima.",
            "cache_control": {
              "type": "ephemeral",
              "ttl": "5m"
            }
          }
        ]
      },
      {
        "role": "user",
        "parts": [
          {
            "text": "Resuma os três principais pontos do material de referência."
          }
        ]
      }
    ]
  }'

cache_control é um campo de extensão da plataforma para o formato de solicitação do Gemini. Depois de identificar o limite, a plataforma remove esse campo antes de encaminhar a solicitação e cria ou reutiliza automaticamente o conteúdo em cache (cachedContent). A interface de streaming usa o mesmo corpo da solicitação; basta alterar o endereço para:

curl -N "https://api.apimart.ai/v1beta/models/gemini-3.6-flash:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "Insira aqui o material de referência extenso que será reutilizado…",
            "cache_control": {
              "type": "ephemeral",
              "ttl": "5m"
            }
          }
        ]
      },
      {
        "role": "user",
        "parts": [
          {
            "text": "Resuma os três principais pontos do material de referência."
          }
        ]
      }
    ]
  }'

Ao reutilizar o cache, mantenha systemInstruction, os contents anteriores ao limite, o TTL e as tools inalterados; modifique apenas o conteúdo em tempo real posterior ao limite.

Fluxo de criação e reutilização

Na primeira vez que você enviar uma solicitação com cache_control:

Identificar o prefixo estável
→ Criar o Context Cache
→ Referenciar o novo cache na solicitação atual
→ Retornar o resultado do modelo

Ao enviar novamente o mesmo prefixo estável:

Identificar o mesmo prefixo estável
→ Reutilizar um Context Cache que ainda não expirou
→ Enviar apenas o conteúdo atual em tempo real
→ Retornar o resultado do modelo

Por isso, a primeira solicitação também pode retornar diretamente uma grande quantidade de tokens provenientes do cache. Esse comportamento é normal e não exige o envio prévio de uma “solicitação de aquecimento”.

Reutilizar o cache

Nas solicitações seguintes, mantenha os itens abaixo inalterados:

O modelo
Todas as mensagens anteriores a cache_control
cache_control.ttl
As definições de ferramentas (se você usar tools)
systemInstruction nas solicitações nativas do Gemini

Modifique apenas a pergunta em tempo real posterior ao limite:

{
  "role": "user",
  "content": "Quais riscos são mencionados no material de referência?"
}

Desde que o prefixo estável seja idêntico e o cache ainda não tenha expirado, o sistema reutilizará o cache existente. As seguintes alterações geram um cache diferente:

Modificar o texto ou a ordem das mensagens no prefixo estável
Trocar o modelo
Alterar 5m para 1h
Modificar as tools ou a definição dos parâmetros das ferramentas
Usar outro usuário ou canal de API

Exemplo em Python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apimart.ai/v1",
)

stable_messages = [
    {
        "role": "system",
        "content": "Responda estritamente de acordo com o material de referência fornecido.",
    },
    {
        "role": "user",
        "content": "Insira aqui o material de referência extenso que será reutilizado…",
    },
    {
        "role": "assistant",
        "content": [
            {
                "type": "text",
                "text": "Li e compreendi o material de referência acima.",
                "cache_control": {
                    "type": "ephemeral",
                    "ttl": "5m",
                },
            }
        ],
    },
]

response = client.chat.completions.create(
    model="gemini-3.6-flash",
    messages=[
        *stable_messages,
        {
            "role": "user",
            "content": "Resuma os três principais pontos do material de referência.",
        },
    ],
)

print(response.choices[0].message.content)
print(response.usage)

Nas solicitações seguintes, reutilize o mesmo stable_messages e substitua apenas a última mensagem do usuário.

Verificar se o cache foi usado

Resposta compatível com a OpenAI

Consulte os seguintes campos da resposta:

{
  "usage": {
    "prompt_tokens": 14430,
    "prompt_tokens_details": {
      "cached_tokens": 14420,
      "cache_write_tokens": 0
    }
  }
}

Descrição dos campos:

Campo	Significado
`prompt_tokens`	Total de tokens de entrada desta solicitação
`cached_tokens`	Tokens de entrada lidos do cache nesta solicitação
`cache_write_tokens`	Tokens gravados no cache; retornar `0` é normal

A primeira solicitação também pode apresentar um valor alto de cached_tokens, pois o sistema pode criar o cache e referenciá-lo na mesma chamada ao modelo.

Resposta nativa do Gemini

Consulte usageMetadata.cachedContentTokenCount na resposta:

{
  "usageMetadata": {
    "promptTokenCount": 13926,
    "cachedContentTokenCount": 13916,
    "totalTokenCount": 13954
  }
}

Descrição dos campos:

Campo	Significado
`promptTokenCount`	Total de tokens de entrada desta solicitação
`cachedContentTokenCount`	Tokens de entrada lidos do cache nesta solicitação
`totalTokenCount`	Total de tokens de entrada e saída desta solicitação

streamGenerateContent retorna o mesmo usageMetadata em um frame da resposta SSE. O cliente deve ler o frame que contém esse campo, em vez de verificar apenas o primeiro trecho de texto.

Recomendações

Armazene em cache apenas conteúdos longos que sejam realmente estáveis e que serão reutilizados várias vezes.
Coloque a pergunta que muda a cada solicitação depois do limite definido por cache_control.
Não inclua timestamps, IDs aleatórios nem informações dinâmicas do usuário no prefixo estável.
Use 5m se você espera repetir as chamadas em um curto período.
Use 1h quando precisar de uma janela de reutilização mais longa.
Se o prefixo for muito curto, o modelo não for compatível ou o cache estiver temporariamente indisponível, a solicitação poderá ser processada automaticamente da maneira convencional.
No formato nativo do Gemini, o limite do cache deve estar em contents[].parts[], e não em systemInstruction.

Perguntas frequentes

O formato de solicitação nativo do Gemini pode criar um cache automaticamente?

Sim. generateContent e streamGenerateContent usam a mesma estrutura de cache_control. O limite deve estar em contents[].parts[], e deve haver pelo menos um content em tempo real depois do content que contém o limite.Se a solicitação já fornecer explicitamente o nome de um recurso cachedContent nativo, a plataforma dará prioridade ao recurso fornecido pelo usuário e não tentará criar um cache automaticamente.

Por que o cache não foi usado?

Os motivos mais comuns incluem:

O prefixo estável não é exatamente igual ao da solicitação anterior
O TTL expirou
O modelo ou as tools foram modificados
O conteúdo armazenado em cache não atingiu o número mínimo de tokens exigido pelo modelo
cache_control foi colocado na última mensagem, sem deixar uma pergunta em tempo real

Posso colocar cache_control na última mensagem?

Não é recomendável. A última mensagem geralmente é a pergunta atual em tempo real e não deve ser armazenada em cache. Se não houver nenhuma mensagem em tempo real depois do limite, a solicitação será processada da maneira convencional.

Posso configurar outro TTL?

Não. No momento, apenas 5m e 1h são compatíveis. Qualquer outro valor retorna um erro HTTP 400.

Posso configurar vários limites de cache?

Sim, mas todos os limites devem usar o mesmo TTL, e o sistema usará o último deles. Em geral, recomendamos configurar apenas um limite por solicitação para deixar a estrutura mais clara.

A solicitação falhará se o cache não estiver disponível?

Normalmente, não. Se as condições para criar ou reutilizar o cache não forem atendidas, o sistema processará automaticamente a solicitação da maneira convencional. As exceções são erros de parâmetros, como um TTL inválido ou o uso combinado de TTLs diferentes.

O que acontece se o modelo não tiver o Context Cache habilitado?

A solicitação será processada automaticamente da maneira convencional, sem criar um cache explícito nem gerar custos de armazenamento em cache. A entrada e a saída normais, bem como eventuais acertos em cache implícito, continuarão a ser cobrados de acordo com as regras existentes do modelo.

Por que cache_write_tokens é 0?

Esse é o comportamento normal do cache de contexto do Gemini. O custo de criação é registrado como uma cobrança separada de armazenamento em cache; cache_write_tokens, no estilo da OpenAI ou do Claude, não é usado para indicar quantos tokens foram gravados no cache.

Um valor de cached_tokens maior que 0 significa que um cache explícito foi criado?

Não necessariamente. O próprio sistema também pode produzir acertos em um cache implícito. Para usuários comuns, os tokens lidos do cache permitem determinar se a solicitação se beneficiou de uma leitura em cache. Se você precisar verificar o custo de criação de um cache explícito, consulte os registros de consumo de Context Cache storage na plataforma.

Como o cache é cobrado?

Ao criar um cache, pode haver uma cobrança única de armazenamento. Ao usar o cache, os tokens correspondentes são cobrados pelo preço de leitura do cache. Consulte os preços específicos na página de preços dos modelos da plataforma.

Visão Geral

Série de Texto

Série de Imagem

Série de Vídeo

Série de Áudio

Série de Moderação

Gerenciamento de Upload

Gerenciamento de Tarefas

Gerenciamento de Conta

Guia de uso do cache de contexto do Gemini

Casos de uso

Uso básico

Estrutura das mensagens

Exemplo de solicitação compatível com a OpenAI

Exemplo de solicitação nativa do Gemini

Fluxo de criação e reutilização

Reutilizar o cache

Exemplo em Python

Verificar se o cache foi usado

Resposta compatível com a OpenAI

Resposta nativa do Gemini

Recomendações

Perguntas frequentes

​Casos de uso

​Uso básico

​Estrutura das mensagens

​Exemplo de solicitação compatível com a OpenAI

​Exemplo de solicitação nativa do Gemini

​Fluxo de criação e reutilização

​Reutilizar o cache

​Exemplo em Python

​Verificar se o cache foi usado

​Resposta compatível com a OpenAI

​Resposta nativa do Gemini

​Recomendações

​Perguntas frequentes

Casos de uso

Uso básico

Estrutura das mensagens

Exemplo de solicitação compatível com a OpenAI

Exemplo de solicitação nativa do Gemini

Fluxo de criação e reutilização

Reutilizar o cache

Exemplo em Python

Verificar se o cache foi usado

Resposta compatível com a OpenAI

Resposta nativa do Gemini

Recomendações

Perguntas frequentes