Gemini 4 Neon Context Caching: como obter o desconto de 95%

O Gemini 4 Neon faz cache automático de prefixos de prompt repetidos e os cobra a US$ 0,15 por 1 milhão em vez de US$ 3. Veja como estruturar seus prompts para obter acertos de cache, o que muda nos loops de agentes e como confirmar os acertos em usage.total_cached_tokens.

Ashley Goolam

Ashley Goolam

19 novembro 2026

Gemini 4 Neon Context Caching: como obter o desconto de 95%

Apidog para empresas

Implantação local

SSO & RBAC

Conforme SOC 2

Explorar Apidog Enterprise

O cache de contexto do Gemini 4 Neon é apenas implícito. Você não cria um cache. O Google faz o cache de prefixos de prompt repetidos com pelo menos 4.096 tokens por conta própria e cobra esses tokens de entrada em cache a US$ 0,15 por 1 milhão em vez de US$ 3, um desconto de 95%. Você obtém esse benefício mantendo a parte estável de cada solicitação no início e idêntica byte a byte, e depois confirmando os acertos em usage.total_cached_tokens.

Abaixo: layout do prompt para acertos de cache, a regra do loop de agente, como ler a contagem de tokens em cache e um teste que seu agente de codificação executa para você.

Como funciona o cache de contexto do Gemini 4 Neon?

O cache de contexto do Gemini 4 Neon é um cache de prefixo automático. Quando uma nova solicitação começa com os mesmos tokens de uma recente, e esse prefixo compartilhado tem pelo menos 4.096 tokens, o Google serve a parte repetida do cache e a cobra pela taxa de cache. Não há nada para ativar, nem objeto de cache, TTL ou taxa de armazenamento para gerenciar.

O Google lançou o Neon em 18 de novembro de 2026 (ID do modelo gemini-4-neon, veja o post de lançamento). Os fatos sobre o cache dele cabem em uma tabela:

Item Gemini 4 Neon
Modo de cache Apenas implícito, ativado por padrão
Cache explícito (cachedContents, caches.create) Não suportado
Prefixo mínimo para um acerto de cache 4.096 tokens
Entrada padrão US$ 3,00 por 1 milhão de tokens
Entrada em cache (Padrão) US$ 0,15 por 1 milhão de tokens
Entrada em cache (Batch e Flex) US$ 0,075 por 1 milhão de tokens
Entrada em cache (Priority) US$ 0,27 por 1 milhão de tokens
Onde ver os acertos usage.total_cached_tokens
Camada gratuita Nenhuma, apenas camada paga

O desconto é de 95% em todas as camadas: US$ 0,15 é 5% de US$ 3, US$ 0,075 é 5% de US$ 1,50 e US$ 0,27 é 5% de US$ 5,40. Os tokens de saída, incluindo os tokens de raciocínio (thinking), permanecem a US$ 15 por 1 milhão na camada Standard. O cache afeta apenas a entrada.

Cache implícito vs. cache explícito no Gemini 4 Neon

Se você usava cache explícito no Gemini 2.5 ou 3, esta é a mudança que quebra o código. As notas de migração do Neon do Google dizem claramente: o Gemini 4 Neon “não suporta cache explícito (cachedContents e caches.create)”, e você deve “remover os campos cached_content das solicitações”.

A documentação de cache acrescenta que a Interactions API só suporta cache implícito, e o cache explícito não está disponível para nenhum modelo Gemini 4. Os caches explícitos ainda funcionam nos modelos Gemini 3 e 2.5 suportados por meio do generateContent.

O que isso significa para uma migração:

  1. Exclua o código que chama caches.create e armazena um nome de cache.
  2. Remova cached_content de todos os corpos de solicitação.
  3. Pare de pagar pelo armazenamento de cache que você não usa mais.
  4. Reestruture os prompts para que o conteúdo que você costumava colocar em cache explicitamente fique no início de cada solicitação.

Você não pode fixar um documento nem escolher um TTL, e um acerto não é garantido. Mas você pode aumentar muito as chances.

Como estruturar prompts para acertar o cache do Gemini 4 Neon?

Um acerto de cache exige um prefixo longo e idêntico enviado novamente em breve. A documentação do Google dá duas dicas: coloque o conteúdo grande e comum no início do seu prompt e envie solicitações com um prefixo semelhante em um curto intervalo de tempo.

Duas solicitações do Gemini 4 Neon compartilhando um prefixo estável idêntico de instrução de sistema, definições de ferramentas e documentos com mais de 4.096 tokens, cobrado a US$ 0,15 por 1 milhão em um acerto de cache, seguido por uma pergunta nova diferente cobrada a US$ 3 por 1 milhão

Organize cada solicitação assim:

  1. Instrução de sistema. Texto fixo, sem timestamps, sem nomes de usuário, sem IDs de solicitação.
  2. Declarações de ferramentas e funções. A mesma lista, na mesma ordem, com as mesmas descrições sempre.
  3. Documentos compartilhados. O código-base, o contrato, a especificação da API, o arquivo longo de políticas.
  4. A parte que muda. A pergunta do usuário, o resultado mais recente da ferramenta, a data de hoje.

A maneira mais comum de errar o cache é um pequeno valor dinâmico perto do topo. Uma linha como Current time: 2026-11-19T09:14:02Z na instrução de sistema muda o prefixo em cada chamada, então nada depois dela pode corresponder. Mova-a para o final, depois dos documentos.

Outros quebradores de prefixo: listas de ferramentas construídas em ordem aleatória, documentos re-serializados com espaços em branco diferentes e chunks recuperados retornados em uma ordem diferente.

Mantenha o prefixo acima de 4.096 tokens. Um prompt de sistema de 2.000 tokens sozinho não se qualifica. Se você enviar um documento compartilhado longo junto com ele, o prefixo combinado se qualifica.

Com a Interactions API, passe a instrução estável em system_instruction e coloque os documentos primeiro em input:

from google import genai

client = genai.Client()  # reads GEMINI_API_KEY

SYSTEM = open("review_rules.md").read()      # fixed text
CODEBASE = open("repo_snapshot.txt").read()  # ~200K tokens, unchanged

def ask(question: str):
    interaction = client.interactions.create(
        model="gemini-4-neon",
        system_instruction=SYSTEM,
        input=CODEBASE + "\n\nQuestion: " + question,
    )
    print("cached tokens:", interaction.usage.total_cached_tokens)
    return interaction

ask("Where do we validate JWT expiry?")
ask("Which handlers skip input validation?")

A primeira chamada preenche o cache. Se a segunda imprimir 0 tokens em cache, algo no prefixo mudou.

O cache implícito funciona nos dois modos de conversa. Chamadas sem estado, como a acima, se qualificam, e sessões com estado encadeadas com previous_interaction_id também. Para os formatos completos de solicitação, consulte nosso guia da API do Gemini 4 Neon.

Como o cache funciona em loops de agente: a regra dos 2.050 tokens

Os loops de agente são onde o cache compensa mais, porque cada turno reenvia todo o histórico. Os modelos Gemini 4 adicionam uma regra que você precisa conhecer. Da documentação de cache do Google: “O Gemini faz o cache da solicitação anterior completa apenas se a nova solicitação adicionar pelo menos 2.050 tokens”. A saída do modelo, os pensamentos e os resultados de funções contam para esse total.

Se um turno adiciona menos de 2.050 tokens, o Gemini reprocessa os últimos 2.050 tokens da solicitação anterior pela taxa de entrada padrão. A parte anterior do prefixo ainda pode ter acerto, mas essa parte final é cobrada a US$ 3 por 1 milhão.

O Google observa que a maioria dos turnos de agente excede o limite. Isso dói em loops muito comunicativos com etapas minúsculas, como uma verificação de status que retorna {"ok": true}. O custo é pequeno por turno (2.050 tokens a US$ 3 por 1 milhão são cerca de US$ 0,006), mas se acumula ao longo de milhares de turnos curtos. Se o seu loop faz muitas chamadas minúsculas, agrupe pequenos resultados de ferramentas em um único turno sempre que sua lógica permitir.

Quanto o cache de contexto do Gemini 4 Neon economiza?

Considere um assistente de revisão de código que responde a 20 perguntas sobre um código-base de 200.000 tokens. Cada pergunta adiciona 3.000 tokens e recebe uma resposta de 1.000 tokens, na camada Standard.

Sem acertos de cache, cada chamada custa:

Com acertos de cache após a primeira chamada, as chamadas de 2 a 20 custam:

Somando a primeira chamada, sem cache, de US$ 0,624, a sessão custa US$ 1,65, cerca de 87% menos.

Gráfico de barras de uma sessão do Gemini 4 Neon respondendo a 20 perguntas sobre um código-base de 200 mil tokens na camada Standard: US$ 12,48 sem acertos de cache e US$ 1,65 com acertos de cache após a primeira chamada

A economia fica abaixo de 95% porque a saída e a entrada nova nunca recebem o desconto. Quanto maior o prefixo compartilhado em relação ao resto, mais perto você chega de 95% na entrada. Execute o mesmo trabalho via Batch e a taxa de cache cai pela metade novamente, para US$ 0,075. Para a tabela completa de preços e os custos por nível de raciocínio, veja preços do Gemini 4 Neon.

Como verificar os tokens em cache do Gemini 4 Neon na resposta?

Leia usage.total_cached_tokens em cada resposta. O Google documenta esse campo como o que mostra quantos tokens foram acertos de cache, tanto no SDK Python quanto no JavaScript.

Com curl e jq:

curl -s "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json | jq '.usage'

Para precificar uma chamada, cobre os tokens em cache a US$ 0,15 por 1 milhão, o resto da sua entrada a US$ 3 e a saída mais raciocínio a US$ 15. Registre a contagem de cache junto com o ID da sua solicitação. Uma queda repentina para 0 em todo o tráfego geralmente significa que um deploy mudou o prefixo: uma nova ferramenta, uma regra reformulada ou um timestamp que entrou na instrução de sistema.

Deixe seu agente de codificação testar acertos de cache com o Apidog CLI

Os prefixos quebram durante refatorações comuns, e ninguém percebe até a conta chegar. Transforme a verificação de cache em um teste de API que seu agente de codificação mantém e o CI executa.

O Apidog CLI permite que Claude Code, Codex, Cursor ou OpenCode criem e executem testes de API no terminal. Configure-o uma vez:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

Depois, dê ao seu agente um único prompt:

In Apidog project <id>, create an environment for the Gemini API with a
GEMINI_API_KEY variable. Build a test scenario called "Neon cache hit" with two
steps that POST to /v1beta/interactions with model gemini-4-neon, using our
production system_instruction and the docs/context.md file as the start of
input, then two different questions. Assert HTTP 200 on both, and assert that
usage.total_cached_tokens on step 2 is greater than 4096. Run it and tell me
the cached token count.

O agente cria o ambiente e o cenário, verifica seu payload contra o schema do CLI e executa:

apidog environment create gemini-api --project <id> --base-url https://generativelanguage.googleapis.com
apidog test-scenario create --project <id> --name "Neon cache hit"
apidog cli-schema get test-scenario-update
apidog cli-schema validate test-scenario-update --file scenario.json
apidog test-scenario update <scenarioId> --project <id> --file scenario.json
apidog run -t <scenarioId> --project <id> -e <envId> -r cli,json

Se alguém adicionar um timestamp ao prompt de sistema no próximo mês, a asserção da etapa 2 falha antes da mudança ir para produção. Coloque apidog run -t <scenarioId> --project <id> -e <envId> -r junit no seu pipeline com o guia de CI/CD do Apidog CLI, ou comece pelo Apidog CLI no Claude Code. Cada execução faz duas chamadas reais ao Neon, então custa alguns centavos por execução nas taxas acima. O plano Free do Apidog cobre até 4 usuários.

Para entender como o cache de prefixo funciona entre provedores, veja o que é cache de prompt.

FAQ

O Gemini 4 Neon suporta cache de contexto explícito? Não. O guia do Neon do Google diz que ele não suporta cachedContents nem caches.create, e que você deve remover cached_content das solicitações. O Neon usa apenas cache implícito, que vem ativado por padrão.

Qual é o tamanho mínimo de prompt para um acerto de cache no Gemini 4 Neon? 4.096 tokens de prefixo compartilhado. É o mesmo mínimo do Gemini 4 Hydrogen, Argon e Carbon. O Gemini 2.5 Flash e Pro exigem 2.048.

Qual é o tamanho do desconto de cache do Gemini 4 Neon? 95% na entrada em cache. A camada Standard cai de US$ 3 para US$ 0,15 por 1 milhão de tokens, Batch e Flex de US$ 1,50 para US$ 0,075, e Priority de US$ 5,40 para US$ 0,27. Os tokens de saída e raciocínio não recebem desconto.

Posso forçar o Gemini 4 Neon a colocar um prompt em cache? Não. O cache implícito não tem nenhuma configuração para ativar, nenhum TTL para escolher e nenhum acerto garantido. Você aumenta as chances mantendo um prefixo longo e idêntico no início de cada solicitação e enviando solicitações semelhantes em sequência próxima.

Como sei se minha solicitação teve acerto de cache? Verifique usage.total_cached_tokens na resposta. Um valor acima de zero significa que aquela quantidade de tokens de entrada foi cobrada pela taxa de cache.

O cache funciona com previous_interaction_id? Sim. A documentação do Google diz que o cache implícito funciona tanto em conversas com estado encadeadas com previous_interaction_id quanto em conversas sem estado, em que você mesmo envia o histórico completo.

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs