Curso
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 SDKgoogle-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
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.

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:

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:
|
|
Capturou a race? |
Correção correta? |
Design da correção |
Latência |
Thinking tokens |
Tokens de saída |
Custo |
|
|
Sim |
Sim |
Locks por pedido + conjunto de concluídos |
7,8 s |
0 |
791 |
US$ 0,0031 |
|
|
Sim |
Sim |
Locks por pedido + dict de estado por pedido |
16,6 s |
3.158 |
627 |
US$ 0,0143 |
|
|
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
lowganhou 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
mediumonde 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
highpara 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:

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:

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)

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_formatnã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=Falsetorna a chamada sem estado, mas aí você não consegue encadear umprevious_interaction_ida 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:

3 coisas aconteceram aqui:
-
O Turn 1 retornou um passo
function_callcom nome, argumentos estruturados e umid. -
Seu Python fez a consulta.
-
O Turn 2 enviou um bloco
function_resultreferenciando 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.
-
Troque o ID do modelo para
gemini-3.8-flash. -
Apague parâmetros mortos de amostragem:
temperature,top_petop_ksão ignorados ou rejeitados no Gemini 3.x, efrequency_penalty,presence_penaltyecandidate_countgeram erro ativo da API. Remova os 6 de configs legadas. -
Substitua
thinking_budgetporthinking_level: use apenaslow,mediumouhigh. O valor minimal antigo retorna erro de validação. Enviarthinking_budgetethinking_leveljuntos em uma requisição retorna 400. -
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.
-
Padronize fluxos multi-turn: confie em
previous_interaction_idem vez de repassar histórico no cliente. Você deve reespecificar suas ferramentas,system_instructionegeneration_configem 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 |
|
|
Campos legados sobrando: |
Corrija a requisição; retry é inútil |
|
|
|
Exporte a chave de novo; verifique se está setada, sem restrições para esta API e não foi commitada no git |
|
|
Rate limit no seu plano, geralmente durante jobs em lote de extração |
Retry com backoff exponencial e jitter; considere distribuir a carga |
|
|
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.idem 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.
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.



