Pular para o conteúdo principal

Tutorial da API Gemini 3.8 Flash: thinking levels, extração de PDF e function calling em Python

Aprenda a usar a API Gemini 3.8 Flash em Python: configuração da Interactions API, ajuste de thinking_level, extração de PDF para JSON e function calling com código.
Atualizado 7 de set. de 2026  · 15 min lido

Explorar com IA

ChatGPTClaudePerplexity

O Google lançou 3 modelos Flash em 6 semanas: o 3.6 no fim de julho, depois o 3.7 Flash em 13 de agosto e agora o Gemini 3.8 Flash em 2 de setembro de 2026. Se você vem do 3.7, a atualização é uma linha, porque a superfície da API é idêntica. Configurações mais antigas ainda quebram se você não ajustar os parâmetros.

Em vez de remendar código legado, este tutorial monta um setup limpo do zero. Vamos inicializar um cliente Python na Interactions API, comparar os 3 níveis de raciocínio em uma tarefa prática de depuração com contagens reais de tokens, extrair JSON com schema limpo de um PDF de fatura e implementar um loop completo de function calling. Por fim, vamos cobrir a checklist de migração para desenvolvedores que estão atualizando a partir do 3.6 Flash ou anterior.

Para acompanhar, você vai precisar do Python 3.10+ e de uma chave da API do Google AI Studio. Este guia foca na implementação em código, não em anúncios de recursos.

Resumo

  • O Gemini 3.8 Flash (gemini-3.8-flash) usa a Interactions API via client.interactions.create() no SDK google-genai

  • A profundidade de raciocínio é definida com valores string (thinking_level: low, medium, high). 

  • As opções legadas de amostragem (temperature, top_p, top_k) morreram 

  • O estado multi-turn é gerenciado no servidor usando previous_interaction_id

  • Preço promocional: US$ 0,75 / US$ 3,75 por milhão de tokens de entrada/saída até 31 de dezembro de 2026. 

  • Se você vem do 3.7 Flash, só muda a string do modelo.

Engenheiro associado de IA para cientistas de dados

Treine e faça o ajuste fino dos modelos de IA mais recentes para produção, incluindo LLMs como o Llama 3. Comece sua jornada para se tornar um engenheiro de IA hoje mesmo!
Explorar a Trilha

O que é o Gemini 3.8 Flash?

O Gemini 3.8 Flash é o modelo de trabalho do Google, disponível publicamente desde 2 de setembro de 2026, com o ID de modelo gemini-3.8-flash. Ele chegou 3 semanas após o 3.7 Flash, e o Google o posiciona para código de longo fôlego, fluxos agentic e raciocínio em múltiplas etapas em domínios especializados como finanças e jurídico.

As especificações que importam para chamadas de API não mudaram em relação ao 3.7: 

  • janela de contexto de 1M de tokens
  • 64k de tokens máximos de saída
  • entrada multimodal (texto, imagens, vídeo, áudio, PDFs) com saída em texto
  • o mesmo preço promocional de US$ 0,75 por 1M de tokens de entrada e US$ 3,75 por 1M de tokens de saída até 31 de dezembro de 2026 (subindo para US$ 1,50 e US$ 7,50 a partir de 1º de janeiro de 2027)

O que mudou foi o comportamento, não a superfície: o Google diz que o 3.8 trabalha mais em tarefas complexas, dando passos extras de raciocínio e chamando ferramentas iterativamente, o que pode elevar o uso de tokens em níveis de esforço mais altos. O 3.7 Flash segue totalmente suportado para workloads onde eficiência importa mais do que profundidade.

Para benchmarks e preços detalhados, confira nosso guia do Gemini 3.8 Flash, ou leia o guia O que é o Google Gemini? para uma visão geral da plataforma.

Gemini 3.8 Flash vs. 3.8 Flash Cyber

O lançamento inclui 2 variantes, e só 1 delas tem um ID de modelo que você pode digitar. 

  • Gemini 3.8 Flash é o modelo geral, disponível hoje no Google AI Studio e na Gemini API. 
  • Gemini 3.8 Flash Cyber é uma variante de cibersegurança ajustada para descoberta de vulnerabilidades e correções automatizadas.

A variante Cyber não está disponível na API pública: o acesso é via Fairwind Program do Google, que é limitado a autoridades governamentais aprovadas, operadores de infraestrutura crítica e mantenedores de software.

Se você está seguindo este tutorial, seu ID de modelo é gemini-3.8-flash. Nada abaixo precisa ou usa a variante Cyber.

Interactions API vs. generateContent

Para chamar o Gemini 3.8 Flash, use client.interactions.create() no SDK google-genai. O Google tornou a Interactions API GA em junho de 2026 e a recomenda para todo trabalho novo. Embora generateContent ainda funcione, agora é legado. Novos recursos como histórico no servidor, execução em background e passos observáveis de execução chegam primeiro na Interactions.

A maior mudança na prática é o gerenciamento de estado. Chamadas multi-turn agora usam um previous_interaction_id no servidor: você passa o ID da última interação, e o servidor cuida da restauração do estado. Você não precisa mais anexar ou reenviar manualmente todo o histórico do chat a partir do cliente. Evite também pré-preencher turns do modelo; esse é um padrão legado de generateContent e vai quebrar no Gemini 3.x.

Tem um ponto que pega quase todo mundo e volta na seção de PDF: previous_interaction_id restaura o histórico da conversa e nada mais. tools, system_instruction, generation_config e response_format são escopados à interação, então qualquer turn que precise deles deve passá-los de novo.

thinking_level substitui os knobs de amostragem

Nos modelos Gemini mais antigos, os desenvolvedores usavam temperature, top_p e top_k para controlar a aleatoriedade da saída. O Gemini 3.x remove esses knobs de amostragem e os substitui por thinking_level, que agora é o único ajuste.

Ele aceita 3 valores:

  • low: menos tokens de raciocínio, mais rápido e barato. Serve para extração, classificação e qualquer coisa que você mesmo vai conferir.

  • medium: o padrão e a recomendação do Google para código e trabalho com agentes.

  • high: o maior orçamento de raciocínio, para lógica difícil em várias etapas e tarefas pesadas em ferramentas.

Não envie minimal. É inválido desde o Gemini Flash 3.7 e retorna um erro 400 de validação. 

Outra regra que vem do 3.7: frequency_penalty, presence_penalty e candidate_count agora geram um erro ativo da API, então remova-os também das configs legadas.

Como configurar a API do Gemini 3.8 Flash?

Configurar seu ambiente leva cerca de 2 minutos. Você precisa de uma chave da API do Google AI Studio e da biblioteca Python atualizada google-genai.

Obtenha uma chave de API no Google AI Studio

Acesse o Google AI Studio no seu navegador e faça login com sua conta Google. Clique em Create API Key, selecione ou crie um projeto do Google Cloud e copie sua chave secreta. 

Gerando uma chave da API do Google AI Studio

Abra seu terminal e salve a chave como variável de ambiente com export GEMINI_API_KEY=<your-key>.

Nunca passe a chave como um parâmetro de consulta ?key= numa URL; query strings vão parar em logs de servidor, histórico do navegador e caches de proxy. Se quiser explorar o modelo em um playground antes de escrever código, o Tutorial do Google AI Studio cobre os modos Chat, Build e Stream; este artigo fica na API.

Para sistemas de produção, a autenticação muda: o Vertex AI (agora parte da Gemini Enterprise Agent Platform) oferece OAuth, papéis de IAM e endpoints regionais em vez de uma chave de API crua. Tudo neste tutorial usa chaves do AI Studio porque é o caminho mais rápido para aprender, mas planeje a migração para o Vertex antes de algo tocar dados reais de usuários.

Instale o google-genai e crie um cliente

Muitos tutoriais ainda mandam instalar google-generativeai. Esse é o SDK antigo e não tem Interactions API. Instale google-genai (versão 2.3.0 ou superior):

pip install -U google-genai

Depois de instalar, verifique se o Python carrega a biblioteca e inicializa seu cliente sem erros:

from google import genai # lê GEMINI_API_KEY do ambiente
client = genai.Client() 
print("Client initialized successfully.")

Faça sua primeira chamada à Interactions API

Cada requisição à Interactions API cria um recurso Interaction, que registra o turno completo: sua entrada, os pensamentos do modelo, eventuais chamadas de ferramentas e a saída final. O SDK expõe o texto final pela propriedade conveniente output_text, então raramente você precisa percorrer os passos manualmente.

from google import genai
client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=(
        "Write a pandas one-liner that adds a 7-day rolling average "
        "revenue column per store_id to a DataFrame with columns "
        "date, store_id, revenue. Reply with only the code, no explanation."
    ),
    generation_config={"thinking_level": "medium"},
)
print(interaction.output_text)
usage = interaction.usage
print(
    f"input={usage.total_input_tokens} | output={usage.total_output_tokens} | "
    f"thinking={usage.total_thought_tokens} | total={usage.total_tokens}"
)

Na minha máquina, o modelo respondeu com um one-liner encadeado em pandas, e esta linha de uso:

Faça sua primeira chamada à Interactions API com o Gemini Flash 3.8

Esses números escondem a primeira diferença real em relação ao 3.7. Rodei a mesma tarefa de novo com um prompt mais longo e sem restrição de saída, e o 3.8 gastou 1.436 tokens de thinking contra 870 de saída. Com a restrição, gastou 1.515 contra 42. O orçamento de raciocínio mal se mexeu, o oposto do 3.7, onde os mesmos 2 prompts fizeram o thinking variar de 838 para 1.530.

Ou seja, o 3.8 decide o quanto pensar com base na tarefa, não em como você formula a tarefa, o que bate com a afirmação do Google de que o modelo raciocina e verifica mais de propósito. Thinking é cobrado na taxa de saída, então, na chamada restrita, cerca de 97% dos tokens cobrados foram raciocínio que eu nunca vi. É por isso que a próxima seção existe. 

Faça streaming da resposta

Para interfaces de chat ou qualquer coisa que uma pessoa acompanha na tela, esperar vários segundos pela resposta completa parece lento. Passe stream=True para client.interactions.create() e imprima os chunks conforme chegarem:

	from google import genai

	client = genai.Client()

	stream = client.interactions.create(
	   model="gemini-3.8-flash",
	   input="Explain the difference between a JOIN and a correlated subquery in SQL.",
	   generation_config={"thinking_level": "low"},
	   stream=True,
	)

	for event in stream:
	   if event.event_type == "step.delta" and event.delta.type == "text":
	       print(event.delta.text, end="", flush=True)
	print() 

Quando rodei, o modelo retornou uma resposta longa e bem organizada em thinking_level: "low": uma comparação conceitual, uma tabela-resumo e 2 exemplos de SQL para encontrar o pedido mais recente de cada cliente, 1 com um join em tabela derivada e 1 com subconsulta correlacionada na lista SELECT. As primeiras palavras apareceram quase imediatamente, que é o objetivo.

Aquele print() final está ali por um motivo. Sem ele, o último chunk termina no meio da linha e o zsh mostra um % perdido antes do seu prompt, porque o stream para exatamente onde o texto do modelo para. Além disso, os deltas só carregam texto; se você registra a contagem de tokens por requisição, leia do evento final de conclusão em vez de somar os chunks.

Como o thinking_level muda custo e qualidade?

thinking_level define quanto raciocínio o Gemini 3.8 Flash faz antes de escrever a resposta. Tokens de raciocínio são cobrados na taxa de saída de US$ 3,75 por 1M, então o nível que você escolher controla diretamente custo e latência, e o Google diz que o 3.8 aposta nisso de propósito: ele dá passos extras em tarefas complexas e pode gastar mais tokens em níveis de esforço mais altos do que o 3.7 gastava.

Rode um único prompt em low, medium e high

O teste é uma condição de corrida em uma função de retentativa de pagamento enviada com o mesmo prompt nos 3 níveis. Bugs de concorrência punem leitura superficial, então, se houver diferença entre os níveis, é aqui que vai aparecer. Se você só rodar 1 bloco de código deste artigo, que seja este, porque os números argumentam melhor do que qualquer texto.

import time

from google import genai

client = genai.Client()

BUGGY_CODE = '''
import threading

payment_attempts = {}

def retry_payment(order_id, charge_fn, max_retries=3):
    """Retry a failed payment up to max_retries times."""
    if order_id not in payment_attempts:
        payment_attempts[order_id] = 0

    while payment_attempts[order_id] < max_retries:
        success = charge_fn(order_id)
        if success:
            del payment_attempts[order_id]
            return True
        payment_attempts[order_id] += 1
    return False
'''

PROMPT = (
    "Two worker threads can call retry_payment() with the same order_id "
    "at the same time. Identify the concurrency bug that can double-charge "
    "a customer, and rewrite the function to fix it.\n\n" + BUGGY_CODE
)

for level in ["low", "medium", "high"]:
    start = time.perf_counter()
    interaction = client.interactions.create(
        model="gemini-3.8-flash",
        input=PROMPT,
        generation_config={"thinking_level": level},
    )
    elapsed = time.perf_counter() - start
    usage = interaction.usage
    print(f"\n=== thinking_level: {level} | {elapsed:.1f}s ===")
    print(interaction.output_text)
    print(
        f"input={usage.total_input_tokens} | output={usage.total_output_tokens} | "
        f"thinking={usage.total_thought_tokens}"
    )

Para contexto, a vulnerabilidade é um check-then-act não atômico em payment_attempts[order_id]. Em concorrência, 2 threads podem passar a condição do while e ambas chamam charge_fn() antes que qualquer uma incremente o contador. Corrigir significa envolver o fluxo ler-checar-cobrar-incrementar em um lock por pedido ou usar uma chave de idempotência no gateway.

Comparando os resultados

Resultados das minhas execuções:

thinking_level

Capturou a race?

Correção correta?

Design da correção

Latência

Thinking tokens

Tokens de saída

Custo

low

Sim

Sim

Locks por pedido + conjunto de concluídos

7,8 s

0

791

US$ 0,0031

medium

Sim

Sim

Locks por pedido + dict de estado por pedido

16,6 s

3.158

627

US$ 0,0143

high

Sim

Sim

Registro por pedido (lock, tentativas, concluído) com caminho de falha documentado

25,5 s

4.512

896

US$ 0,0204

Os 3 níveis encontraram a dupla cobrança, e todos entregaram locking por pedido, então pedidos não relacionados rodam em paralelo. Essa 2ª parte é a manchete se você comparar com o 3.7: lá, o low envolvia tudo em um lock global mantido durante a chamada de rede, e locks por pedido só apareciam no medium. No 3.8, o low escreve esse design melhor com 0 tokens de thinking, em 7,8 segundos, por menos de um terço de centavo.

Então o que os níveis compram agora? Profundidade de auditoria. Este código tem 4 modos distintos de falha (a dupla cobrança, um KeyError ao deletar concorrentemente, uma recobrança depois que o caminho de sucesso apaga o estado e incrementos de contador não atômicos), e o high foi o único nível a nomear todos os 4; o low perdeu o caso de recobrança e o medium perdeu o contador. 

high também foi o único a detalhar a semântica do caminho de falha da sua correção: quando as retentativas se esgotam, chamadas posteriores recebem False em vez de cobrar de novo.

A coluna de thinking é a afirmação do "3.8 trabalha mais" do Google aparecendo no terminal. Com o mesmo prompt no 3.7, o medium foi de 2.343 tokens de thinking para 3.158, e o high de 2.217 para 4.512, aproximadamente o dobro, e os tokens extras compraram uma análise mais completa, não um veredito diferente. A latência subiu junto nesta execução (7,8 s, 16,6 s, 25,5 s), mas tempos de execução únicos nesses modelos variam, então compare contagens de tokens em vez de segundos.

Escolha um padrão e quando escalar

Esta é minha regra prática para os níveis de raciocínio:

  • No 3.8, o low ganhou um papel maior do que o padrão medium do Google sugere: ele produziu uma correção correta e bem desenhada com 0 tokens de thinking, então comece por ele para qualquer coisa que um humano leia antes de valer (triagem, rascunhos, resumos, código que você vai revisar). 

  • Mantenha o medium onde a saída vai sem leitura, porque o raciocínio extra trouxe uma análise mais completa de modos de falha, e um pipeline não lido é exatamente onde o modo de falha que você não listou é o que dispara.

  • Reserve o high para saídas onde o próprio caminho de falha é o produto, como fluxos de pagamento, migrações ou qualquer coisa que um revisor auditasse linha a linha. No meu teste, foi o único nível a pegar os 4 bugs e documentar o que acontece depois que as retentativas se esgotam.

A 6.6x o custo do low para o high, essa troca soa bem diferente a US$ 3,75 por 1M de tokens de saída agora versus US$ 7,50 após 31 de dezembro de 2026, então escale por requisição, não globalmente.

Uma saída de emergência que vale conhecer é que o Google afirma que o 3.7 Flash permanece totalmente suportado para workloads com foco em eficiência. Se a diligência extra do 3.8 custa mais do que sua tarefa precisa, ficar no gemini-3.7-flash para esse workload é uma escolha suportada, não um hack.

Como extrair dados estruturados de um PDF?

O Gemini 3.8 Flash lê PDFs diretamente como entrada, então você pode enviar uma fatura ou um relatório e fazer perguntas sobre ele. Usei uma fatura de fornecedor de 1 página com número da fatura, datas, 4 itens de linha e um total.

Anexe um PDF ao prompt

Vamos enviar um PDF local de fatura usando a Files API. A Files API cuida do armazenamento e do cache do arquivo na infraestrutura do Google:

	from google import genai
	client = genai.Client()
	print("Uploading invoice...")
	doc = client.files.upload(file="invoice_aug_2026.pdf")
	print(f"File uploaded: {doc.uri}\n")

	interaction = client.interactions.create(
	   model="gemini-3.8-flash",
	   input=[
	       {
	           "type": "text",
	           "text": "Extract the invoice number, total amount due, and due date.",
	       },
	       {"type": "document", "uri": doc.uri, "mime_type": doc.mime_type},
	   ],
	)
	print(interaction.output_text)

A saída da minha fatura:

Ler um PDF com o Gemini 3.8 Flash

Os 3 valores estão corretos. O upload acontece uma vez e o arquivo fica disponível para requisições futuras, o que importa assim que você fizer mais de 1 pergunta sobre o mesmo documento. A resposta volta como bullets em markdown, o que é ótimo para leitura e ruim para alimentar um pipeline.

Force JSON com um schema de resposta

Para obter JSON em vez de prosa, passe um schema em response_format. Na Interactions API, isso é um parâmetro de topo; a configuração responseMimeType dentro de generationConfig que você verá em tutoriais antigos pertence ao endpoint legado generateContent.

import json

from google import genai
from pydantic import BaseModel

client = genai.Client()


class Invoice(BaseModel):
    invoice_number: str
    total_due_usd: float
    due_date: str  # ISO 8601


doc = client.files.upload(file="invoice_aug_2026.pdf")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "text",
            "text": "Extract the invoice number, total amount due in USD, and due date.",
        },
        {"type": "document", "uri": doc.uri, "mime_type": doc.mime_type},
    ],
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": Invoice.model_json_schema(),
    },
)

invoice = json.loads(interaction.output_text)
print(invoice)

Esta foi a saída que recebi: 

Forçar formato JSON

Sua classe Pydantic define os campos obrigatórios e tipos de dados, enquanto model_json_schema() gera o schema JSON exigido pela API do Gemini. Depois de processado, json.loads() converte a saída do modelo em um dicionário Python padrão. A partir daqui, os dados estruturados estão prontos para virar uma linha de DataFrame, irem para o banco ou serem adicionados a uma planilha do Google.

Faça uma pergunta de acompanhamento com previous_interaction_id

Para uma 2ª pergunta sobre o mesmo documento, passe o id da 1ª interação como previous_interaction_id. O servidor já tem o PDF e a 1ª troca, então você não envia nenhum deles de novo:

follow_up = client.interactions.create(
    model="gemini-3.8-flash",
    previous_interaction_id=interaction.id,
    input="List each line item on the invoice with its amount.",
)

print(follow_up.output_text)

Pergunta de acompanhamento para PDF

Ele retornou os 4 itens em ordem, incluindo a linha de compute repetida, sem comentar sobre a repetição. Isso é o comportamento certo para a pergunta feita; se você quiser que ele aponte anomalias, peça por isso. 

Para constar, o 3.7 se comportou de forma idêntica aqui, então a diligência extra do 3.8 se aplica ao próprio raciocínio, não a se voluntariar para auditorias que você não pediu.

2 coisas para saber sobre essa chamada: 

  • response_format não foi mantido, porque é escopado à interação, então este turn voltou em prosa. 

  • E interações são armazenadas por padrão (store=True) por 55 dias no plano pago e 1 dia no plano gratuito; store=False torna a chamada sem estado, mas aí você não consegue encadear um previous_interaction_id a partir dela.

Como adicionar function calling ao Gemini 3.8 Flash?

Function calling no Gemini 3.8 Flash é um único loop: o modelo pede uma ferramenta, seu código a executa, você envia o resultado de volta e o modelo escreve a resposta final. Esta seção constrói esse loop na mão.

Se você quer que o Google rode o loop por você com agentes hospedados de múltiplas ferramentas, leia nosso tutorial sobre  "Managed Agents" na Gemini API em seguida. E se agentes são seu destino no longo prazo, o curso Building AI Agents with Google ADK constrói um assistente completo de suporte ao cliente com as mesmas primitivas.

Defina uma ferramenta e execute o loop de interação

A ferramenta é lookup_exchange_rate(currency, date), apoiada por um pequeno dict em memória, para o exemplo rodar sem uma API externa. A declaração é um schema JSON. O modelo nunca executa a função; ele retorna um passo function_call pedindo ao seu código para:

import json

from google import genai

client = genai.Client()

# "Fonte de dados" local no lugar de uma API real de câmbio
RATES = {
    ("USD", "2026-08-03"): 87.42,
    ("USD", "2026-08-10"): 87.15,
    ("EUR", "2026-08-03"): 95.08,
}


def lookup_exchange_rate(currency: str, date: str) -> dict:
    rate = RATES.get((currency.upper(), date))
    if rate is None:
        return {"error": f"No rate for {currency} on {date}"}
    return {"currency": currency.upper(), "date": date, "inr_rate": rate}


rate_tool = {
    "type": "function",
    "name": "lookup_exchange_rate",
    "description": "Look up the INR exchange rate for a currency on a date (YYYY-MM-DD).",
    "parameters": {
        "type": "object",
        "properties": {
            "currency": {"type": "string", "description": "ISO code, e.g. USD"},
            "date": {"type": "string", "description": "YYYY-MM-DD"},
        },
        "required": ["currency", "date"],
    },
}

# Turn 1: o modelo decide chamar a ferramenta
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="What was the USD to INR exchange rate on 2026-08-03?",
    tools=[rate_tool],
)

fc_step = next(s for s in interaction.steps if s.type == "function_call")
print(f"Model requested: {fc_step.name}({fc_step.arguments})")

# Seu código executa a função localmente
result = lookup_exchange_rate(**fc_step.arguments)

# Turn 2: envie o resultado de volta; tools devem ser reespecificadas (escopo da interação)
final = client.interactions.create(
    model="gemini-3.8-flash",
    previous_interaction_id=interaction.id,
    input=[
        {
            "type": "function_result",
            "name": fc_step.name,
            "call_id": fc_step.id,
            "result": [{"type": "text", "text": json.dumps(result)}],
        }
    ],
    tools=[rate_tool],
)

print(final.output_text)

A saída: 

Function calling no Gemini 3.8 Flash

3 coisas aconteceram aqui:  

  1. O Turn 1 retornou um passo function_call com nome, argumentos estruturados e um id.

  2. Seu Python fez a consulta.

  3. O Turn 2 enviou um bloco function_result referenciando aquela chamada. 

O parâmetro tools é passado novamente no turn 2 pelo mesmo motivo que response_format teve que ser repassado na seção de PDF: previous_interaction_id carrega histórico, não configuração.

Erros comuns de function calling no Gemini 3.x

Se um loop de ferramenta quebra, quase sempre é 1 de 2 motivos. 

Primeiro, todo resultado precisa mapear de volta para sua chamada. Na Interactions API, isso é call_id e name no bloco function_result; na API legada generateContent, o FunctionResponse deve corresponder ao id e name do FunctionCall anterior. Nenhum é opcional no Gemini 3.x.

Segundo, um erro Malformed_Function_Call geralmente ocorre quando o modelo emite comentários antes da chamada da ferramenta. O guia para desenvolvedores do 3.8 do Google diz para limpar o texto antes da ferramenta, formatar instruções inline com \n\n e envolver notas de trabalho em uma chamada de função dedicada em vez de texto cru. Aperte a system instruction; não tente novamente às cegas.

O que quebra ao mudar para o Gemini 3.8 Flash?

Depende de onde você começa. 

  • Do Gemini 3.7 Flash: nada. Mude a string do modelo para gemini-3.8-flash, e cada snippet deste artigo roda sem modificação, já que a superfície da API é idêntica. 

  • Do Gemini 3.6 Flash ou anterior, a configuração do modelo exige a mesma auditoria de 15 minutos de antes.

Checklist de migração (a partir do 3.6 Flash ou anterior)

Siga estes passos na ordem. Itens de 1 a 3 causam 400 imediatos; itens 4 e 5 causam problemas silenciosos de qualidade.

  1. Troque o ID do modelo para gemini-3.8-flash.

  2. Apague parâmetros mortos de amostragem: temperature, top_p e top_k são ignorados ou rejeitados no Gemini 3.x, e frequency_penalty, presence_penalty e candidate_count geram erro ativo da API. Remova os 6 de configs legadas.

  3. Substitua thinking_budget por thinking_level: use apenas low, medium ou high. O valor minimal antigo retorna erro de validação. Enviar thinking_budget e thinking_level juntos em uma requisição retorna 400.

  4. Remova turns pré-preenchidos do modelo: elimine-os de qualquer conversa construída e garanta que o último turn do usuário tenha texto não vazio. Payloads de histórico não podem terminar com um turn do modelo.

  5. Padronize fluxos multi-turn: confie em previous_interaction_id em vez de repassar histórico no cliente. Você deve reespecificar suas ferramentas, system_instruction e generation_config em todo turn em que importem.

O Google publica a versão autoritativa na documentação de modelos da Gemini API, incluindo um caminho automatizado se seu agente de código suportar skills. Leia você mesmo uma vez, ainda assim; uma migração automática não vai te dizer por que seu temperature=0.2 estava lá em primeiro lugar.

Erros que você vai encontrar em produção

Aqui estão os 4 status codes para os quais vale a pena criar handlers, e o que cada um realmente significa nesta API:

Status

Causa típica

O que fazer

400 INVALID_ARGUMENT

Campos legados sobrando: temperature, thinking_budget, thinking_level: "minimal", frequency_penalty, presence_penalty, candidate_count, turns pré-preenchidos do modelo

Corrija a requisição; retry é inútil

403 PERMISSION_DENIED

GEMINI_API_KEY errada, ausente ou restrita, ou um projeto sem acesso ao modelo

Exporte a chave de novo; verifique se está setada, sem restrições para esta API e não foi commitada no git

429

Rate limit no seu plano, geralmente durante jobs em lote de extração

Retry com backoff exponencial e jitter; considere distribuir a carga

503

Sobrecarga transitória do lado do Google

Mesmo backoff com jitter; alerte só se persistir por alguns minutos

Mais 2 itens aqui:

  • Defina timeouts explícitos no cliente ao combinar thinking_level: "high" com loops longos de ferramentas, porque uma requisição travada é pior do que uma com falha, e a diligência extra do 3.8 torna execuções longas de raciocínio mais prováveis, não menos. 

  • E registre interaction.id em toda requisição; é sua alça para recuperar, depurar ou excluir interações armazenadas depois.

Considerações finais

Tudo neste artigo volta a 3 mudanças. A Interactions API mudou a convenção de chamada, thinking_level substituiu todos os knobs de amostragem que você usava para ajustar, e o estado no servidor via previous_interaction_id foi o que tornou tanto o follow-up do PDF quanto o loop de ferramentas turns de 1 linha em vez de exercícios de replay de histórico. O Gemini 3.8 Flash não mudou nada dessa superfície; o que mudou foi o quanto o modelo trabalha dentro dela, por isso as medições deste artigo foram feitas do zero no 3.8 e não reaproveitadas do 3.7.

Antes de aceitar minhas recomendações de níveis na fé, aponte o script de comparação para uma tarefa do seu próprio backlog; o nível que vence numa corrida de retentativa de pagamento pode perder no seu workload de geração de SQL. 

Quando chamadas únicas de API não forem mais suficientes e você quiser sistemas de IA em produção, nossa Associate AI Engineer for Developers cobre o caminho completo, e a Associate AI Engineer for Data Scientists faz o mesmo pelo lado de dados.

FAQs

Qual pacote Python devo instalar para o Gemini 3.8 Flash?

Instale google-genai usando pip (pip install -U google-genai). A biblioteca mais antiga google-generativeai é legada e falha quando você passa argumentos de configuração do Gemini 3.x.

O Gemini 3.8 Flash suporta temperature, top_p ou top_k?

Não. Parâmetros de amostragem estão mortos no Gemini 3.x, e o 3.8 ainda lança um erro ativo da API para frequency_penalty, presence_penalty e candidate_count. Você controla o comportamento da saída com thinking_level.

Quais valores de thinking_level o Gemini 3.8 Flash aceita?

Ele aceita low, medium (padrão) e high. O valor minimal é inválido e retorna um erro de validação da API.

Como o Google cobra os tokens de raciocínio no Gemini 3.8 Flash?

O Google conta tokens de raciocínio como tokens de saída padrão a US$ 3,75 por 1M de tokens durante o período promocional, que termina em 31 de dezembro de 2026. O Google também observa que o 3.8 pode gastar mais tokens de raciocínio em níveis de esforço mais altos, então você paga pelos ciclos extras de verificação.

O que é o Gemini 3.8 Flash Cyber e posso usá-lo?

É uma variante de cibersegurança ajustada para descoberta de vulnerabilidades e correções automatizadas. Não está na API pública; o acesso é limitado a defensores aprovados via Fairwind Program do Google. Desenvolvedores em geral usam gemini-3.8-flash.


Aryan Irani's photo
Author
Aryan Irani
Twitter

Eu escrevo e crio na internet. Especialista em desenvolvimento do Google para o Google Workspace, formado em Ciência da Computação pela NMIMS e apaixonado por automação e IA generativa.

Tópicos
Inteligência Artificial
Modelos de idiomas grandes

Aprenda IA com a DataCamp!

Curso

Introduction to Google Workspace with Gemini

30 min
2.2K
You learn about the key features of Gemini and how they can be used to improve productivity and efficiency in Google Workspace.
Ver detalhesRight Arrow
Iniciar Curso
Ver maisRight Arrow
Relacionado

Tutorial

Tutorial de chamada de função do OpenAI

Saiba como o novo recurso de Chamada de Função da OpenAI permite que os modelos GPT gerem saída JSON estruturada, resolvendo problemas comuns de desenvolvimento causados por saídas irregulares.
Abid Ali Awan's photo

Abid Ali Awan

8 min

Tutorial

Guia para iniciantes no uso da API do ChatGPT

Este guia o orienta sobre os conceitos básicos da API ChatGPT, demonstrando seu potencial no processamento de linguagem natural e na comunicação orientada por IA.
Moez Ali's photo

Moez Ali

11 min

Tutorial

DeepSeek-Coder-V2 Tutorial: Exemplos, instalação, padrões de referência

O DeepSeek-Coder-V2 é um modelo de linguagem de código de código aberto que rivaliza com o desempenho do GPT-4, Gemini 1.5 Pro, Claude 3 Opus, Llama 3 70B ou Codestral.
Dimitri Didmanidze's photo

Dimitri Didmanidze

8 min

Tutorial

Primeiros passos com o Claude 3 e a API do Claude 3

Saiba mais sobre os modelos Claude 3, benchmarks de desempenho detalhados e como acessá-los. Além disso, descubra a nova API Python do Claude 3 para geração de texto, acesso a recursos de visão e streaming.
Abid Ali Awan's photo

Abid Ali Awan

Tutorial

Tutorial da API de assistentes da OpenAI

Uma visão geral abrangente da API Assistants com nosso artigo, que oferece uma análise aprofundada de seus recursos, usos no setor, orientação de configuração e práticas recomendadas para maximizar seu potencial em vários aplicativos de negócios.
Zoumana Keita 's photo

Zoumana Keita

14 min

Tutorial

Um guia para iniciantes na engenharia de prompts do ChatGPT

Descubra como fazer com que o ChatGPT forneça os resultados que você deseja, fornecendo a ele as entradas necessárias.
Matt Crabtree's photo

Matt Crabtree

6 min

Ver MaisVer Mais