Gemini 3.8 Flash: Níveis de Raciocínio Baixo, Médio e Alto e o Fim do Nível Mínimo

O Gemini 3.8 Flash vem com três níveis de raciocínio: low, medium e high. A configuração controla quanto raciocínio interno o modelo realiza antes de responder e, neste modelo, ela altera três métricas de uma só vez: latência, tokens de saída e sua fatura. O Google construiu o 3.8 Flash para “trabalhar mais” em tarefas complexas por design, então o nível que você escolhe importa mais do que no 3.7 Flash. Se você é novo no modelo, a visão geral do Gemini 3.8 Flash aborda o lançamento. Este guia é apenas sobre a configuração.

Dois detalhes confundem as equipes na primeira hora. O nível padrão no 3.8 Flash é medium, não high (o Gemini 3 Pro usa high como padrão, de onde vem a confusão). E minimal, que configurações escritas para o Gemini 3.7 Flash ainda enviam, não é mais aceito: a requisição falha na validação antes que um único token seja gerado. O Google documenta ambos na página Novidades no Gemini 3.8 Flash.

Abaixo: o que cada nível faz, quanto custa por tarefa, como configurá-lo em ambas as formas de API, uma estratégia por rota e um teste repetível que mostra a diferença de tokens e latência antes de você implantar.

Níveis de raciocínio em um relance

As colunas de custo e tempo são médias da Artificial Analysis, obtidas ao executar seu Índice de Inteligência em cada nível, com os preços introdutórios por token do Google. São números independentes, não do Google, e medem uma carga de trabalho de benchmark, não seus prompts. Use-os para proporções, depois meça suas próprias rotas.

O que cada nível faz

Cada resposta do 3.8 Flash pode incluir tokens de raciocínio: raciocínio que o modelo gera antes da resposta visível. Você paga por eles como tokens de saída (US$ 3,75 por milhão na taxa introdutória até 31/12/2026, US$ 7,50 a partir de 01/01/2027), e a API os reporta separadamente como usageMetadata.thoughtsTokenCount. O nível de raciocínio informa ao modelo quanto desse raciocínio deve ser realizado.

• low mantém o raciocínio breve. O primeiro token chega mais rápido e a fatura de saída permanece baixa. O Google o posiciona para trabalhos sensíveis à latência: seguir instruções simples, chat e endpoints de alto throughput.
• medium é o ponto de equilíbrio e o padrão. O Google o destaca como a configuração para código complexo e tarefas de agente, que é a maior parte do que as pessoas executam em um modelo da classe Flash.
• high diz ao modelo para raciocinar o mais profundamente possível. O Google o reserva para os problemas multi-etapas mais difíceis.

O que torna isso diferente no 3.8 Flash é o novo comportamento padrão do modelo. Em tarefas complexas, ele "executa etapas de raciocínio adicionais e chama ferramentas iterativamente" e "verifica seu trabalho ao longo do caminho". O Google afirma claramente que ele "pode usar mais tokens em tarefas mais longas e complexas, por design" e que "o modelo pode usar mais tokens para maximizar o desempenho, especialmente em níveis de esforço mais altos". O nível de raciocínio é o acelerador desse comportamento. Reduzi-lo é a primeira sugestão do próprio Google quando o uso de tokens aumenta; a segunda é permanecer no 3.7 Flash, que continua totalmente suportado.

Uma restrição para internalizar: thinking_level é um enum, não um orçamento. O inteiro thinking_budget de modelos anteriores não existe mais no Gemini 3, então você não pode pedir "no máximo 2.000 tokens de raciocínio". Você escolhe um nível e então verifica o custo em seus prompts, e é por isso que o teste no final deste guia é importante.

O padrão é medium, não high

Omita o campo e o 3.8 Flash rodará em medium. Isso afeta dois grupos.

Equipes que prototiparam no Gemini 3 Pro esperam high por padrão e obtêm respostas de profundidade média sem perceber. Equipes que removeram thinking_budget durante uma atualização do 3.7 Flash e não o substituíram por um nível acabam em medium em todos os lugares, incluindo as rotas de chat que deveriam estar em low.

A solução para ambos é a mesma: defina thinking_level explicitamente em cada requisição, por rota, na configuração, não no código. Os padrões são do Google para mudar; seu perfil de custo não deve se alterar quando eles o fazem.

Por que minimal foi removido e como corrigir o erro

minimal funcionava no Gemini 3.7 Flash. No 3.8 Flash, ele não está no conjunto suportado, e a página do modelo lista o raciocínio apenas como low, medium e high. Envie-o via REST e a requisição será rejeitada antes que o modelo seja executado com um 400 INVALID_ARGUMENT com a mensagem “Thinking level MINIMAL is not supported for this model. Please retry with other thinking level.” (verificado com uma chamada ao vivo em 3 de setembro de 2026). SDKs encapsulam isso em sua própria classe de exceção, então combine pelo status 400 ou pelo código INVALID_ARGUMENT, não pela string da mensagem.

Antes:

{
  "model": "gemini-3.8-flash",
  "input": "Classify this ticket as billing, bug, or feature.",
  "generation_config": { "thinking_level": "minimal" }
}

Depois:

{
  "model": "gemini-3.8-flash",
  "input": "Classify this ticket as billing, bug, or feature.",
  "generation_config": { "thinking_level": "low" }
}

A orientação de migração do Google é um mapeamento direto: minimal torna-se low. Duas tentações a evitar enquanto você estiver nessa configuração. Não use thinking_budget para obter um limite inferior menor; ele não é suportado nos modelos Gemini 3. E não diminua temperature para "acalmar o modelo"; o Google recomenda deixá-lo no padrão 1.0 em todos os modelos Gemini 3, pois diminuí-lo pode causar loops ou saída degradada. A lista de verificação completa, incluindo assinaturas de pensamento e o requisito de call_id nas respostas de função, está no guia de migração do 3.7 para 3.8 Flash.

Como o erro é disparado no momento da validação, uma requisição de teste agendada em cada nível detecta gratuitamente uma configuração que regride para minimal.

Quanto cada nível custa por tarefa

O preço por token não muda com o nível. A página de preços do Google lista cada chamada do 3.8 Flash a US$ 0,75 de entrada e US$ 3,75 de saída por milhão de tokens na taxa introdutória, dobrando para US$ 1,50 e US$ 7,50 em 01/01/2027. A diferença entre os níveis é puramente a contagem de tokens, que é o que a Artificial Analysis mediu.

Fonte: Artificial Analysis, execuções do Índice de Inteligência com preços introdutórios. Três proporções se destacam da tabela.

low opera a cerca de 41% do custo de high e cerca de um terço do seu tempo de execução. Essa é a maior alavanca que você tem neste modelo.

medium no 3.8 Flash custa aproximadamente o mesmo que high custava no 3.7 Flash (US$ 0,41 vs US$ 0,40). Se você estava satisfeito com o 3.7 Flash em high, o 3.8 Flash em medium é a linha de orçamento equivalente.

high no 3.8 Flash custa 45% mais por tarefa do que high no 3.7 Flash, com preços por token idênticos, porque o modelo emite cerca de 30% mais tokens de saída (48 mil em média por tarefa de índice). Esse é o design de "trabalha mais" aparecendo na fatura. Se os tokens extras se pagam, depende da carga de trabalho; a comparação 3.8 Flash vs 3.7 Flash detalha onde os ganhos de qualidade se manifestaram.

Uma ressalva sobre a qualidade: a pontuação de 59 no Índice de Inteligência da AA para o 3.8 Flash é uma execução em high. Eles não publicaram pontuações de índice em medium ou low no texto, então não presuma que a curva de qualidade é linear com o custo. Teste suas próprias avaliações em cada nível antes de rebaixar uma rota. Para o exemplo prático de 1.000 tarefas por dia em cada nível e o "cliff" de preço de 31 de dezembro, veja preços do Gemini 3.8 Flash.

Configurando thinking_level na API de Interações

A API de Interações é a superfície principal do Google para o Gemini 3.x. O nível está em generation_config como uma string no formato snake_case:

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" -H 'Content-Type: application/json' \
  -d '{"model":"gemini-3.8-flash","input":"Explain HTTP caching in 3 sentences.","generation_config":{"thinking_level":"low"}}'

Em Python:

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain HTTP caching in 3 sentences.",
    generation_config={"thinking_level": "low"},
)
print(interaction.output_text)

É um campo de nível de requisição, então configure-o em cada chamada, incluindo turnos de acompanhamento que passem previous_interaction_id. A resposta retorna como uma lista de etapas de execução (pensamentos, chamadas de ferramentas) terminando em model_output, e o SDK expõe o texto final como output_text. Para o passo a passo completo da primeira chamada, incluindo estado multi-turno e streaming, veja como usar a API Gemini 3.8 Flash.

Configurando-o em generateContent legado

A maioria do código Gemini existente ainda chama generateContent. O Google o chama de legado, mas afirma que ele continua totalmente suportado sem data de descontinuação, então não há pressa. O campo está aninhado um nível mais profundo e em camelCase:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" -H 'Content-Type: application/json' -X POST \
  -d '{"contents":[{"parts":[{"text":"Explain HTTP caching in 3 sentences."}]}],
       "generationConfig":{"thinkingConfig":{"thinkingLevel":"low","includeThoughts":true}}}'

Em Python:

from google.genai import types

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Explain HTTP caching in 3 sentences.",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="low")
    ),
)
print(response.usage_metadata.thoughts_token_count)

includeThoughts: true adiciona resumos de pensamentos à resposta como partes marcadas com thought: true: útil durante a calibração de um nível, ruído quando você terminar. O número que importa é usageMetadata.thoughtsTokenCount, a contagem exata faturada como saída e o campo que seus testes devem monitorar.

Uma estratégia por rota

Trate o nível como uma decisão de roteamento, não como uma configuração global. Uma divisão viável:

• Chat, preenchimento automático e qualquer coisa que uma pessoa esteja esperando: low. É onde a latência do primeiro token se manifesta.
• Classificação, extração e pesquisa de transcrições: low, com sua própria avaliação executada uma vez para confirmar a precisão. O próprio exemplo de vídeo do Google coloca a pesquisa de transcrições em low.
• Agentes de codificação e loops de ferramentas: medium, o padrão. Eleve uma única etapa de planejamento para high se sua saída bloquear todas as etapas seguintes, e depois retorne. No 3.8 Flash, os loops de ferramentas já executam mais turnos por design, então high em um loop inteiro se acumula rapidamente.
• Fluxos de trabalho com muitos documentos e de longo prazo: high, e passe-os pela API em lote com 50% de desconto quando não forem interativos.
• Vídeo: Os documentos do Google fornecem três exemplos. high para Q&A visual denso ou vídeos com mais de 60 minutos, medium para Q&A geral de vídeo, low para pesquisa de transcrição.

Se low no 3.8 Flash ainda for mais modelo do que uma rota precisa, a linha Flash-Lite existe para essa tarefa; nosso guia anterior do Gemini 3.1 Flash-Lite aborda o trade-off, e o Gemini 3.5 Flash-Lite é a entrada atual a US$ 0,30 de entrada e US$ 2,50 de saída.

Mantenha o nível na configuração por rota e mantenha gemini-3.7-flash atrás de uma flag. Se a contagem de tokens de uma rota disparar após a atualização, você pode diminuir o nível ou o modelo sem um novo deploy.

Teste os três níveis lado a lado no Apidog

A leitura da tabela da AA informa as proporções. Apenas seus prompts fornecem os números. Aqui está um cenário de teste no Apidog que envia um prompt "golden" em cada nível e verifica o que foi retornado. Ele funciona contra qualquer uma das formas da API; o endpoint legado é mostrado porque usageMetadata é um campo de nível superior ali.

1. Armazene a chave como uma variável de ambiente. Crie GEMINI_API_KEY em um ambiente Apidog e referencie-o como {{GEMINI_API_KEY}} no cabeçalho x-goog-api-key. Adicione uma segunda variável, THINKING_LEVEL, para que uma única requisição salva sirva a todas as três etapas.
2. Salve uma requisição. Faça um POST para /v1beta/models/gemini-3.8-flash:generateContent com seu prompt "golden" e "thinkingConfig": {"thinkingLevel": "{{THINKING_LEVEL}}"}.
3. Construa um cenário de teste de três etapas. Importe a mesma requisição três vezes e sobrescreva THINKING_LEVEL para low, medium e high em cada etapa.
4. Afirme sobre os campos que mudam. Em cada etapa: o status é 200 e usageMetadata.thoughtsTokenCount existe. Na etapa low, afirme que thoughtsTokenCount e o tempo de resposta permanecem abaixo do limite que a rota pode tolerar (defina a linha de base após a primeira execução). Um script pós-processamento pode armazenar a contagem de cada etapa em uma variável para que a etapa high possa afirmar que raciocinou pelo menos tanto quanto low. Se essa ordem for invertida, o modelo ou o padrão mudou sem você saber.
5. Adicione uma etapa de guarda. Envie thinkingLevel: "minimal" e afirme que a resposta não é um 200. Quando você posteriormente trocar os IDs do modelo, esta etapa informará se o novo modelo ainda o rejeita.
6. Agende-o. Execute o cenário diariamente para que uma regressão de configuração ou uma mudança de comportamento silenciosa apareça como uma execução em vermelho, não como uma fatura surpresa. Os detalhes estão em como agendar testes de API no Apidog.

Para respostas transmitidas, o mesmo cenário se aplica com a renderização SSE; como testar APIs LLM que transmitem via SSE cobre a configuração. Baixe o Apidog para acompanhar; o plano gratuito cobre todo este cenário.

Perguntas Frequentes

O nível de raciocínio altera o preço por token?

Não. A entrada custa US$ 0,75 e a saída US$ 3,75 por milhão de tokens no 3.8 Flash na taxa introdutória, independentemente do nível. O nível altera quantos tokens de saída o modelo gera como raciocínio, e estes são faturados pelo preço de saída. A discriminação de preços cobre cache, lote e o aumento de 1º de janeiro.

Posso definir um orçamento exato de tokens de raciocínio em vez disso?

Não nos modelos Gemini 3. thinking_budget foi substituído pelo enum thinking_level, e o 3.8 Flash aceita apenas low, medium e high. Se você precisar de um limite, imponha-o em testes e alertas em vez de na requisição.

Qual nível é usado para a pontuação de 59 do Artificial Analysis?

high. A AA executou o Índice de Inteligência em high para a pontuação principal e publicou custo e tempo também para low e medium, mas não as pontuações do índice nesses níveis. Considere os níveis mais baixos como não testados nesse benchmark até que você execute suas próprias avaliações.

Devo reduzir a temperatura para diminuir o raciocínio?

Não. A orientação do Google para todos os modelos Gemini 3 é manter a temperature em seu padrão de 1.0. Reduzi-la pode causar loops ou saída degradada. Use thinking_level para controlar a profundidade do raciocínio.

E se mesmo low for muito lento ou muito caro?

Mantenha-se no Gemini 3.7 Flash, que o Google afirma permanecer totalmente suportado sem data de descontinuação, ou mova a rota para um modelo Flash-Lite. A comparação entre 3.8 e 3.7 Flash mostra onde os tokens extras trazem qualidade mensurável e onde não.

Escolha o nível por rota, depois meça-o

Três níveis, um enum, e um modelo que raciocina mais do que seu predecessor por padrão. Defina thinking_level explicitamente em cada rota, mapeie qualquer minimal restante para low, e observe usageMetadata.thoughtsTokenCount onde cada nível se posiciona. Os valores por tarefa da AA (US$ 0,24, US$ 0,41, US$ 0,58) fornecem o formato da curva; um cenário de três etapas no Apidog fornece seus próprios números antes que a mudança de preço de 31 de dezembro os torne duas vezes mais importantes.