Descontinuação do Gemini 2.5: checklist antes do redirecionamento automático em 1º de dezembro

A descontinuação do Gemini 2.5 entra em vigor em 1º de dezembro de 2026. Nessa data, as chamadas ao gemini-2.5-pro e ao gemini-2.5-flash começam a ser direcionadas automaticamente para outros modelos. A maioria das requisições vai continuar funcionando, e é exatamente por isso que vale olhar para isso agora.

Este guia explica o que o Google anunciou, o impacto na fatura, os parâmetros que precisam ser reescritos e como decidir, por workload, entre aceitar o redirecionamento ou fixar um modelo de forma deliberada. Se você usa o Gemini na Vertex AI, leia essa seção primeiro. A data de aposentadoria lá já passou.

O que o Google anunciou e o que realmente muda em 1º de dezembro

As notas de versão da Gemini API do Google, publicadas em 2 de novembro de 2026, informam que as chamadas ao gemini-2.5-pro serão direcionadas automaticamente para o gemini-3.8-flash, e as chamadas ao gemini-2.5-flash, para o gemini-3.5-flash-lite. As notas definem 1º de dezembro de 2026 como a data de início do redirecionamento. A partir daí, qualquer requisição à API que ainda cite um desses modelos será respondida por outro modelo, mais novo, e cobrada pelos preços dele.

O escopo é mais estreito do que a manchete sugere. A página de descontinuações do Gemini informa que o gemini-2.5-flash-lite não foi descontinuado e continua disponível até novo aviso. Apenas dois IDs de modelo são afetados.

O problema prático é que, em geral, nada retorna erro. Um modelo diferente respondendo em silêncio pode passar despercebido.

Por que um redirecionamento silencioso é mais arriscado do que um erro

Do lado do Google, redirecionar é um padrão sensato, porque as equipes que perderem o aviso continuam no ar. Isso também significa que qualidade de saída, latência, uso de tokens e custo podem mudar mesmo que ninguém do lado do cliente tenha mexido no código.

Os mantenedores da biblioteca open source llm-exe levantaram esse ponto em uma issue no GitHub: as chamadas continuam funcionando, mas os usuários do gemini-2.5-pro recebem um modelo da categoria Flash sem nenhum aviso. Eles classificam isso como uma perda real de capacidade e dizem que é "pior do que um 404, porque ninguém vai perceber".

O Google deixou algumas perguntas em aberto. O aviso não explica por que o 2.5 Pro é mapeado para um modelo Flash em vez de uma categoria superior, nem diz se os clientes podem recusar o redirecionamento automático.

Sugerimos tratar a virada como uma troca de modelo que sua equipe não escolheu e revisá-la como um upgrade planejado, com uma rodada de avaliação, uma verificação de custos e a aprovação de um responsável.

O panorama de custos: mais barato em dezembro, diferente a partir de janeiro de 2027

O post de lançamento do Gemini 3.8 Flash do Google traz um preço promocional de $0.75 por 1M de tokens de entrada e $3.75 por 1M de tokens de saída até 31 de dezembro de 2026. O Gemini 2.5 Pro custa $1.25 e $10.00 em prompts de até 200,000 tokens. A partir de 1º de janeiro de 2027, os preços do 3.8 Flash dobram para $1.50 e $7.50. Com esses valores, a entrada fica mais cara do que era no 2.5 Pro, embora a saída continue mais barata.

Dois workloads ilustrativos

Uma análise independente da Data Studios percorre dois workloads de exemplo. Eles não são benchmarks nem medições da Optijara.

No exemplo do assistente de suporte, a fatura mensal cai de $9,300 para $4,500 em dezembro e depois volta a subir para $9,000 a partir de janeiro de 2027. Os volumes de tokens por trás desses totais estão na análise da Data Studios, então confira esses dados lá antes de comparar com o seu próprio tráfego.

A linha de documentos longos lista suas premissas, então você pode recalculá-la com a tabela de preços. O total chega a $810 no 2.5 Pro porque cada prompt cai na faixa mais cara de contexto longo. No 3.8 Flash, o custo é de $240 em dezembro e $480 a partir de janeiro, porque o 3.8 Flash não tem sobretaxa de contexto longo.

A contagem de tokens importa mais do que o preço do token

O post de lançamento do Google diz que o 3.8 Flash pode usar mais tokens para maximizar o desempenho, principalmente em níveis de esforço mais altos. Um volume maior pode consumir parte ou toda a vantagem de um preço por token menor. Meça as contagens reais de tokens no seu próprio tráfego antes de confiar em qualquer planilha, incluindo os exemplos acima.

Mudanças de parâmetros que quebram ou alteram o comportamento em silêncio

thinking_budget vira thinking_level

Os modelos Gemini 3.x usam thinking_level em vez de thinking_budget. O Gemini 3.8 Flash aceita os níveis low, medium e high, e a documentação do modelo 3.8 Flash do Google informa que minimal retorna erro. Confirme a redação atual no changelog da Gemini API e na página do modelo.

Este é um dos poucos pontos em que uma requisição redirecionada pode falhar de vez, então verifique qualquer código, configuração ou wrapper que defina minimal ou faça mapeamento para esse nível. Sugerimos também testar como um valor residual de thinking_budget se comporta em uma requisição redirecionada.

Os parâmetros de amostragem estão de saída

A orientação de migração do Google recomenda que os desenvolvedores removam temperature, top_p e top_k. Esses parâmetros estão descontinuados, são ignorados hoje e vão retornar HTTP 400 em gerações futuras. Remova também candidate_count, já que o Gemini 3 e as versões posteriores não oferecem suporte a ele. Consulte o changelog da Gemini API e a página de descontinuações antes de mexer no código.

Isso não é apenas uma questão do redirecionamento. A documentação da Gemini API do Google confirma que esses parâmetros de amostragem são ignorados no Gemini 3.6 Flash, no Gemini 3.5 Flash-Lite e no Gemini 3.5 Flash Cyber. Se você chama esses modelos, algumas das suas configurações talvez já não tenham efeito nenhum. Um fluxo que dependia de temperatura baixa para manter a saída consistente perdeu esse controle, então teste a consistência diretamente.

O caminho do 2.5 Flash para o 3.5 Flash-Lite

Sugerimos separar o que está documentado nesse caminho do que sua equipe ainda precisa testar ou pesquisar.

• Conhecido: limites de saída. O Gemini 3.5 Flash-Lite, substituto do 2.5 Flash, tem uma janela de contexto de 1M de tokens e aceita até 64,000 tokens de saída. Verifique se as suas configurações de saída máxima e a sua lógica de chunking se encaixam nisso.
• Conhecido: parâmetros de amostragem. Já são ignorados no 3.5 Flash-Lite, como mencionado acima.
• A testar: níveis de thinking. Sugerimos testar cada valor de thinking_level que você pretende enviar, incluindo minimal.
• A pesquisar: custo. Sugerimos calcular o preço desse caminho com base nas tabelas publicadas atualmente pelo Google.

Chamada de ferramentas e de funções

A chamada de ferramentas precisa de uma rodada de testes própria. Sugerimos testar novamente, de ponta a ponta, cada fluxo de chamada de ferramentas no modelo de destino, cobrindo seleção de ferramentas, formatação de argumentos, estado em múltiplos turnos e tratamento de erros. Pode ser mais seguro para as equipes considerar o comportamento anterior como não verificado até que esses testes passem.

Playbook: checklist de migração do Gemini 2.5 em sete etapas

Sugerimos definir um responsável e uma data-alvo para cada etapa antes da virada.

• [ ] Etapa 1, inventário. Procure gemini-2.5-pro e gemini-2.5-flash em código, configurações, variáveis de ambiente, templates de infraestrutura e wrappers de SDK, incluindo valores padrão dentro de bibliotecas de terceiros e frameworks de agentes. Exclua gemini-2.5-flash-lite.
• [ ] Etapa 2, classificação. Marque cada chamada por risco de negócio (voltada ao cliente, com raciocínio intensivo, com chamada de ferramentas, em lote, de contexto longo) e defina um responsável.
• [ ] Etapa 3, reescrita de parâmetros. Substitua thinking_budget por thinking_level (low, medium ou high; sem minimal no 3.8 Flash). Teste cada nível no 3.5 Flash-Lite. Remova temperature, top_p, top_k e candidate_count.
• [ ] Etapa 4, novos testes. Execute um conjunto fixo de avaliação e seus fluxos de chamada de ferramentas no modelo de destino, comparando qualidade, latência e uso de tokens com uma linha de base do modelo atual.
• [ ] Etapa 5, modelo de custos. Calcule o preço do uso de tokens medido em cada caminho.
• [ ] Workloads do 2.5 Pro: com os preços do 3.8 Flash de dezembro de 2026 e depois com os de janeiro de 2027.
• [ ] Workloads do antigo Flash: sugerimos calcular com base nas tabelas publicadas atualmente pelo Google para o modelo de destino.
• [ ] Etapa 6, decisão. Fixe cada workload em um ID de modelo explícito ou registre por escrito que você aceita o destino do redirecionamento.
• [ ] Etapa 7, monitoramento depois de 1º de dezembro. Registre em log o ID do modelo solicitado e todos os metadados de modelo ou versão que a resposta retornar, e crie um alerta para quando forem diferentes. O ID solicitado, sozinho, não revela um redirecionamento. Acompanhe tokens e gastos, e observe o cache, já que o Google não documentou como respostas ou caches se comportam sob redirecionamento.

Na Etapa 7, traces por requisição que registram modelo solicitado, modelo informado, contagem de tokens e latência deixam qualquer desvio visível rapidamente. Nosso playbook de tracing GenAI com OpenTelemetry pode ser um ponto de partida útil para esse tipo de tracing.

Fixar de propósito ou aceitar o redirecionamento: a Revisão de Três Controles

Chamamos nosso framework para essa decisão de Revisão de Três Controles. Dê a cada workload uma nota baixa, média ou alta em cada controle.

• Risco. Quem vê a saída e o que acontece quando ela está errada? Respostas voltadas ao cliente, conteúdo regulado e chamadas de ferramentas que alteram dados recebem nota alta.
• Dependência de raciocínio. Você escolheu o 2.5 Pro pelo raciocínio em múltiplas etapas ou ele apenas virou o padrão?
• Sensibilidade a custo. Quanto do seu gasto com Gemini vem desse workload e com que rapidez ele está crescendo?

Se o risco ou a dependência de raciocínio for alto, sugerimos testar primeiro e fixar explicitamente o modelo que passar. Se ambos forem baixos e a sensibilidade a custo for alta, aceitar o destino do redirecionamento é razoável, mas fixe esse modelo explicitamente mesmo assim. Notas mistas vão para avaliação, com os preços de janeiro como critério de desempate. Workloads de contexto longo merecem atenção especial, já que o exemplo ilustrativo acima ainda mostra economia depois da mudança de janeiro.

O post de lançamento do Google também diz que, quando a eficiência de computação é a principal restrição, os desenvolvedores podem usar níveis de esforço menores ou continuar com o Gemini 3.7 Flash, que segue com suporte total para workloads focados em eficiência. Se a eficiência for sua principal restrição, sugerimos incluir esse modelo na sua avaliação como opção de fixação.

O Google informa uma pontuação de 54.9% para o 3.8 Flash no HLE-Verified. Esse é um contexto informado pelo fornecedor, não uma prova de que o modelo serve para a sua tarefa. Sugerimos deixar que o seu próprio conjunto de avaliação decida, e nosso artigo sobre por que pontuações de benchmark precisam de protocolos traz mais leitura sobre como ponderar números de destaque.

Sugerimos fixar explicitamente mesmo quando você escolher o modelo que o redirecionamento teria escolhido. Uma fixação pode transformar um padrão do fornecedor em uma decisão documentada, que a equipe pode revisitar conforme os preços mudam. Se o tráfego passa por um gateway, considere aplicar fixações explícitas de modelo na camada do gateway para que um valor padrão perdido em algum serviço não consiga contorná-las.

Vertex AI: a data de aposentadoria já passou

A tabela de ciclo de vida da Vertex lista 20 de outubro de 2026 como data de aposentadoria tanto do gemini-2.5-pro quanto do gemini-2.5-flash. Essa data já ficou para trás. Chamadas na Vertex AI que ainda citam um desses modelos podem já estar falhando ou sendo atendidas por outro modelo, então verifique os logs e as taxas de erro desta semana para esses IDs antes de passar para a Developer API.

A Vertex AI documenta os ciclos de vida dos modelos separadamente da Gemini Developer API. O Google diz que, ao agendar a aposentadoria de um modelo nessa plataforma, publica uma data fixa que dá pelo menos 45 dias para a migração. Os substitutos sugeridos também são diferentes: gemini-3.8-flash ou gemini-3.5-flash para o Pro, e gemini-3.8-flash ou gemini-3.5-flash-lite para o Flash. O aviso de redirecionamento do Google não diz como a mudança de 1º de dezembro se aplica à Vertex AI. Se você usa as duas plataformas, verifique cada uma segundo as próprias regras.

Erros comuns das equipes nesta migração

• Capturar a linha de base tarde demais. Depois de 1º de dezembro, uma chamada da Gemini API ao gemini-2.5-pro não chega mais ao 2.5 Pro.
• Deixar passar valores padrão em CI e fixtures de teste. Sugerimos verificar fixtures, mocks, smoke tests e configurações de staging em busca de IDs de modelo hard-coded.
• Manter caches e avaliações com chaves nos IDs antigos. Tudo o que usa a string do modelo como chave pode acabar misturando resultados antigos e redirecionados sob o mesmo rótulo. Refaça as chaves ou marque a data da virada.
• Ajustar alertas de orçamento durante dezembro. Limites definidos com base nos gastos de dezembro vão subestimar janeiro, quando os preços do 3.8 Flash dobram.
• Migrar as chamadas erradas ou deixar passar as ocultas. gemini-2.5-flash-lite não foi descontinuado, e IDs afetados podem estar escondidos em wrappers de terceiros que a busca no seu repositório não vai encontrar.

Ressalvas e questões em aberto

O Google não disse se as respostas vão mostrar que uma requisição redirecionada foi atendida pelo modelo substituto. Também não disse o que acontece com caches de contexto explícitos criados em modelos Gemini 2.5, e não há nenhuma opção de recusa anunciada.

Os cenários de custo apresentados aqui vêm de uma análise independente com workloads ilustrativos. Sua combinação de tráfego, o tamanho dos prompts e as configurações de esforço vão produzir números diferentes. As métricas de benchmark são informadas pelo fornecedor. Preços e documentação podem mudar, então sugerimos conferir novamente o changelog oficial e as páginas de descontinuação antes de agir.

Se uma segunda opinião ajudar, a Optijara pode fazer uma auditoria de migração das suas chamadas ao Gemini ou ajudar a construir a linha de base de avaliação que servirá de comparação.