Gemini 3.7 Flash para 3.8 Flash: Guia de Migração de API

O Google lançou o Gemini 3.8 Flash em 2 de setembro de 2026, três semanas após o 3.7 Flash, com o mesmo preço de lançamento e aproximadamente a mesma velocidade. O ID do modelo é gemini-3.8-flash, sem sufixo de pré-visualização, e o cartão do modelo o descreve como "baseado no Gemini 3.7 Flash". Assim, a maioria das equipes espera uma troca de uma linha. Para um prompt de chat simples, é isso. Para qualquer coisa que defina parâmetros de pensamento, ajuste a amostragem ou execute um ciclo de ferramentas, há nove coisas a verificar, e duas delas retornam erros que o 3.7 Flash nunca apresentou.

Este guia é essa lista de verificação, construída a partir da página do Google Novidades no Gemini 3.8 Flash e do guia do desenvolvedor do Gemini 3. Cada item tem um fragmento antes e depois para ambas as formas da API: a API de Interações, que o Google agora trata como o caminho principal, e o endpoint legado generateContent que a maioria do código do 3.7 Flash ainda usa. Cada fragmento pode ser colado no Apidog e enviado para o endpoint em tempo real antes de tocar na produção. Se você quiser primeiro uma visão geral do modelo, comece com o que é o Gemini 3.8 Flash.

Uma nota introdutória antes da lista. O Google afirma que o 3.8 Flash "trabalha mais" por design: em tarefas complexas, ele dá passos de raciocínio menores, verifica seu trabalho e chama ferramentas iterativamente. Essa é a fonte da maioria de seus ganhos e também a razão pela qual uma migração exige uma revisão do orçamento de tokens, não apenas uma diferença de configuração.

O que muda e o que não muda

Fonte para as linhas de preço: a página de preços da API Gemini do Google, onde as linhas do 3.6, 3.7 e 3.8 Flash são idênticas.

Passo 0: decida se deve migrar

Nada força a migração. A publicação de lançamento do Google afirma que "o Gemini 3.7 Flash permanece totalmente suportado", e nenhuma data de descontinuação é publicada. O preço por token não mudou, então a única diferença de custo é o uso. A Artificial Analysis mediu o 3.8 Flash com pensamento elevado usando cerca de 48 mil tokens de saída por tarefa em seu índice, 30% a mais que o 3.7 Flash, o que moveu o custo por tarefa de $0.40 para $0.58 com taxas idênticas. Sua pontuação no índice subiu de 56 para 59, e a precisão no uso de ferramentas no τ³-Banking subiu 12 pontos para 45%.

Portanto, a troca é mais capacidade por tarefa por mais tokens por tarefa. Se sua carga de trabalho é curta, sensível à latência ou já está passando em suas avaliações no 3.7 Flash, você pode permanecer. A comparação completa entre 3.8 Flash e 3.7 Flash tem uma matriz de decisão por carga de trabalho. Se você for migrar, continue lendo.

Passo 1: troque o ID do modelo em ambas as formas

API de Interações (API principal do Google para Gemini 3.x):

{"model": "gemini-3.7-flash", "input": "..."}
{"model": "gemini-3.8-flash", "input": "..."}

generateContent Legado (ainda suportado, sem descontinuação):

POST /v1beta/models/gemini-3.7-flash:generateContent
POST /v1beta/models/gemini-3.8-flash:generateContent

SDK Python, ambos os caminhos:

client.interactions.create(model="gemini-3.8-flash", input=..., generation_config={"thinking_level": "medium"})
client.models.generate_content(model="gemini-3.8-flash", contents=..., config=types.GenerateContentConfig(thinking_config=types.ThinkingConfig(thinking_level="low")))

Se você nunca usou a API de Interações, o guia da API 3.8 Flash cobre ambas as formas de ponta a ponta; o passo a passo da API 3.7 Flash mais antigo cobria apenas generateContent, razão pela qual este guia mostra ambos.

A lista de verificação de migração de nove itens

Trabalhe estes itens em ordem. Os itens 1 a 4 são alterações de configuração que aparecem imediatamente. Os itens 5 e 6 afetam os ciclos de ferramentas e o estado multiturno. Os itens 7 a 9 são alterações de planejamento e mídia que você só detectará nos testes.

1. Mapeie thinking_level: "minimal" para "low"

Este é o que quebra primeiro. O 3.8 Flash aceita low, medium e high. Enviar minimal retorna um erro de validação. O padrão quando você não envia nada é medium. O Gemini 3 Pro padroniza para high, então não copie uma configuração Pro e presuma que ela corresponda.

Antes (3.7 Flash, Interações):

{"generation_config": {"thinking_level": "minimal"}}

Depois (3.8 Flash):

{"generation_config": {"thinking_level": "low"}}

Forma legada, depois:

{"generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}}

A documentação de pensamento do Google descreve low como a configuração de latência e medium como o padrão para código complexo e trabalho agêntico. Qual nível usar por rota é um artigo à parte; para fins de migração, low é o substituto direto para minimal.

2. Remova temperature, top_p e top_k

A orientação do Google para todos os modelos Gemini 3 é manter a temperatura em seu padrão de 1.0. Reduzi-la "pode causar loops ou degradação de desempenho". Muitas configurações do 3.7 Flash carregam uma temperature: 0.2 restante de gerações anteriores. Exclua as chaves de amostragem em vez de defini-las.

Antes:

{"generationConfig": {"temperature": 0.2, "topP": 0.9, "topK": 40}}

Depois:

{"generationConfig": {"thinkingConfig": {"thinkingLevel": "medium"}}}

Se você usou uma temperatura baixa para obter JSON repetível, use saídas estruturadas. Elas são suportadas no 3.8 Flash e fornecem uma resposta com formato de esquema sem tocar na amostragem.

3. Substitua thinking_budget por thinking_level

thinking_budget era um limite de tokens inteiro. thinking_level é uma enumeração de string. Não há mapeamento aritmético entre eles, então escolha o nível por intenção: rotas de latência recebem low, rotas padrão recebem medium, rotas mais difíceis de múltiplos passos recebem high.

Antes:

{"generationConfig": {"thinkingConfig": {"thinkingBudget": 4096}}}

Depois:

{"generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}}

Os tokens de pensamento ainda são cobrados como tokens de saída e relatados em usageMetadata.thoughtsTokenCount, então o controle de custo passa de um limite rígido para uma escolha de nível mais uma asserção em seus testes (consulte a seção de regressão abaixo).

4. Remova candidate_count

O Gemini 3 e posteriores não suportam múltiplos candidatos. Remova a chave e qualquer código que indexava candidates[1] ou além.

Antes:

{"generationConfig": {"candidateCount": 2}}

Depois:

{"generationConfig": {}}

Se você amostrava vários candidatos para escolher o melhor, o substituto no 3.8 Flash é um nível de pensamento mais alto, que faz a verificação dentro de uma única resposta.

5. Coloque call_id e name em cada resultado de função

Esta é a segunda quebra difícil. No 3.8 Flash, cada resultado de função que você envia de volta deve conter tanto o id da chamada quanto o name da função. O guia Gemini 3 do Google afirma para "garantir que todos os objetos FunctionResponse incluam call_id e name". O código que apenas ecoava o nome falhará na etapa de resultado da ferramenta.

API de Interações, depois:

{
  "previous_interaction_id": "<id da etapa function_call>",
  "input": [{
    "type": "function_result",
    "name": "get_weather",
    "call_id": "<id da etapa function_call>",
    "result": [{"type": "text", "text": "{\"temp_c\": 24}"}]
  }]
}

A etapa function_call do modelo fornece id, name e arguments; copie os dois primeiros diretamente de volta. Na forma legada, a parte functionResponse carrega o mesmo valor em um campo chamado id (correspondendo ao id na parte functionCall do modelo) junto com name e response. A referência de chamada de função do Google tem os exemplos canônicos, e o guia de chamada de função do 3.8 Flash percorre o ciclo completo de duas etapas, incluindo por que o 3.8 Flash chama ferramentas mais vezes por tarefa do que o 3.7 Flash.

6. Passe as assinaturas de pensamento de volta exatamente como recebidas

Os modelos Gemini 3 anexam assinaturas de pensamento às partes da resposta. Quando você constrói a próxima etapa, retorne cada parte inalterada, incluindo as assinaturas, para todos os tipos de partes, não apenas texto. Remover ou resserializá-las degrada a continuidade do modelo na próxima etapa.

A API de Interações remove esse trabalho quando você permite que o servidor mantenha o estado: passe previous_interaction_id e o Google mantém o histórico. Se você definir store: false para uma chamada sem estado, você será responsável pelo histórico novamente e deverá enviar os blocos de pensamento e as assinaturas de volta. Em generateContent legado, você sempre é responsável pelo histórico, então audite qualquer código que reconstrói o contents a partir de uma cópia truncada da última resposta.

7. Orçamente mais tokens por rota

Este item não tem erro a ser detectado, por isso é esquecido. O valor de +30% de tokens de saída da Artificial Analysis é uma média em seu índice com pensamento elevado. A própria formulação do Google é que o modelo "pode usar mais tokens em tarefas mais longas e complexas, por design" e que o uso aumenta "especialmente em níveis de esforço mais altos".

Planeje por rota, não globalmente:

• Endpoints sensíveis à latência: low. A AA mediu 0,8 minutos por tarefa em nível baixo contra 2,5 em nível alto, e $0,24 por tarefa contra $0,58.
• Rotas padrão: medium, a cerca de $0,41 por tarefa no mesmo índice.
• Loops de agente: espere mais etapas de chamada de ferramenta por tarefa, então limite o loop pelo número de etapas, não apenas por tokens.

Revise também o teto de 65.536 tokens de saída. Um prompt do 3.7 Flash que retornava 40k tokens com pensamento pode agora se aproximar do limite. Se você está modelando a fatura, a análise de preços do 3.8 Flash calcula os números por tarefa em todos os três níveis.

8. Teste media_resolution_high em PDFs versus vídeo

O 3.8 Flash aceita entrada de texto, imagem, vídeo, áudio e PDF. A configuração de resolução de mídia altera quantos tokens cada entrada de mídia consome, e o custo difere por tipo de mídia, então a mesma configuração que é barata em uma página de PDF pode ser cara em um vídeo longo. Não use uma configuração global de alta resolução do 3.7 Flash sem medir. Envie um PDF representativo e um vídeo representativo em cada resolução e compare usageMetadata.promptTokenCount entre eles.

9. Remova quaisquer chamadas de segmentação de imagem

A segmentação de imagem não é suportada nos modelos Gemini 3. Se um pipeline da era do 3.7 Flash ainda roteava a segmentação por um modelo Gemini mais antigo, esse caminho é separado desta migração; se um prompt pedisse ao 3.8 Flash por máscaras de segmentação, espere que ele falhe em vez de retornar uma saída utilizável. Geração de imagem, geração de áudio e a Live API também não são suportadas no 3.8 Flash, de acordo com a página do modelo.

Crie o plano de regressão no Apidog

Uma migração com duas alterações disruptivas e uma mudança no uso de tokens precisa de uma comparação repetível, não de um `curl` único. Aqui está a configuração que usamos no Apidog, que funciona porque o Apidog é um cliente de API e um executor de testes: ele envia as requisições, verifica as respostas e agenda a execução. Ele não executa o modelo.

Ambiente e variáveis. Crie um ambiente Gemini com GEMINI_API_KEY armazenada como uma variável secreta e uma variável MODEL. Use {{MODEL}} na URL da requisição generateContent e no campo model da requisição de Interações, para que a mesma requisição salva seja executada contra qualquer modelo.

Prompts dourados. Salve de 10 a 20 prompts que representam suas rotas reais: uma breve conversa de chat, uma extração de saída estruturada, uma chamada de função de duas etapas com uma ferramenta simulada, uma entrada de PDF e uma de vídeo. Cada um é uma requisição em um cenário de teste.

Asserções. Adicione três por requisição:

• Status 200, e o corpo da resposta corresponde a um esquema JSON. Para rotas de saída estruturada, faça asserções nos campos que você analisa downstream.
• usageMetadata.thoughtsTokenCount permanece abaixo de um teto que você define por rota (por exemplo, 8.000 em uma rota low). Esta é a guarda que detecta uma configuração que silenciosamente retornou para medium.
• usageMetadata.totalTokenCount permanece abaixo do orçamento da rota do item 7.

Lado a lado. Duplique o cenário, defina MODEL para gemini-3.7-flash em um e gemini-3.8-flash no outro, e execute ambos. Os relatórios de teste do Apidog mostram aprovação/falha por asserção e os corpos das respostas, então a diferença de token por prompt é visível em uma única visualização, em vez de ser reconstruída a partir de logs. Para o cenário de chamada de função, adicione uma asserção de que o call_id que você enviou de volta é igual ao id da function_call da etapa anterior.

Agende. Transforme o cenário do 3.8 Flash em uma execução agendada para que os tetos de token sejam verificados diariamente durante a janela de lançamento. O guia de testes de API agendados cobre a configuração. Se preferir acompanhar no aplicativo, baixe o Apidog e importe os fragmentos curl acima.

Rollback: mantenha o 3.7 Flash atrás de uma flag de configuração

Como o 3.7 Flash permanece totalmente suportado e compartilha o preço do 3.8 Flash, o rollback é barato: mantenha o ID do modelo na configuração, e não no código.

{"gemini_model": "gemini-3.8-flash", "gemini_fallback_model": "gemini-3.7-flash"}

Três regras tornam a flag segura:

• Mantenha a forma de requisição migrada em ambos os modelos. Os itens 1 a 6 (sem minimal, sem chaves de amostragem, thinking_level em vez de thinking_budget, sem candidate_count, call_id + name, assinaturas preservadas) são todos válidos também no 3.7 Flash, então uma flag invertida nunca precisa de um segundo caminho de código.
• Implemente por rota. Inverta primeiro as rotas de latência de nível low, pois sua diferença de token é a menor; inverta os loops de agente por último, depois que o cenário lado a lado tiver passado por alguns dias.
• Monitore tokens, não apenas erros. Um gatilho de rollback no 3.8 Flash é mais provável que seja uma regressão de custo ou latência do que um 4xx, então conecte as asserções de limite de token ao seu sistema de alerta.

FAQ

O Gemini 3.8 Flash custa mais que o 3.7 Flash? Não por token. Ambos custam $0.75 de entrada / $3.75 de saída por 1M até 31 de dezembro de 2026, e ambos sobem para $1.50 / $7.50 em 1º de janeiro de 2027. Por tarefa, o 3.8 Flash usa mais tokens por design; a Artificial Analysis mediu cerca de 30% mais tokens de saída em seu índice com pensamento elevado.

O que acontece se eu deixar thinking_level: "minimal" no lugar? A requisição falha com um erro de validação no 3.8 Flash. Substitua por low. O guia de níveis de pensamento explica o que cada nível restante faz e como medir a diferença.

Preciso migrar para a API de Interações para usar o 3.8 Flash? Não. generateContent é descrito como legado, mas permanece totalmente suportado sem data de descontinuação, e o 3.8 Flash funciona nele. A API de Interações adiciona estado de conversa do lado do servidor via previous_interaction_id, o que elimina a contabilidade de assinaturas de pensamento no item 6.

O 3.7 Flash está sendo descontinuado? O Google diz que ele "permanece totalmente suportado" e não publicou uma data de descontinuação. É isso que torna o rollback com flag de configuração viável.

Posso manter a mesma temperatura que ajustei para o 3.7 Flash? A recomendação do Google para todos os modelos Gemini 3 é deixar a temperatura em 1.0. Se você já estava sobrescrevendo no 3.7 Flash, esta migração é o momento de removê-la e verificar suas avaliações; saídas estruturadas são o caminho suportado para formas determinísticas.

Lance em etapas

A migração em si é pequena: uma mudança de ID, quatro exclusões ou renomeações de configuração, dois campos de loop de ferramentas e uma auditoria de assinatura. A parte que leva tempo é provar que o orçamento de tokens se mantém por rota, e isso é um problema de teste. Salve os prompts dourados, faça asserções no esquema e nos limites de tokens, execute o 3.7 e o 3.8 Flash lado a lado até que os números se estabilizem, e então ative a flag uma rota por vez. Se uma rota regredir, a flag a envia de volta para o 3.7 Flash sem alteração de código, e você mantém as rotas melhoradas.