Como Usar a Gemini 3.8 Flash API: API de Interações, Níveis de Pensamento e Sua Primeira Chamada no Apidog

O Google lançou o Gemini 3.8 Flash em 2 de setembro de 2026, e o ID do modelo da API é a string simples gemini-3.8-flash, sem sufixo de pré-visualização. Ele mantém o preço de introdução do 3.7 Flash de $0.75 por milhão de tokens de entrada e $3.75 por milhão de tokens de saída até 31 de dezembro de 2026, e o Google o descreve como um modelo que "trabalha mais": ele realiza mais etapas de raciocínio e chama ferramentas com mais frequência em tarefas complexas, o que se reflete na sua fatura de tokens.

Este guia cobre o caminho completo para uma integração funcional: obter uma chave no AI Studio, enviar uma primeira solicitação através da API de Interações (a API primária do Google para Gemini 3.x agora), o equivalente legado generateContent que a maioria do código existente ainda usa, onde o thinking_level se encaixa em cada um, streaming e como ler o thoughtsTokenCount para que o custo de pensamento nunca o surpreenda. Cada chamada é HTTP puro com JSON, para que você possa construir e verificar cada uma no Apidog antes que vá para o código da aplicação.

Para a visão geral do modelo, benchmarks e o que mudou, comece com o que é o Gemini 3.8 Flash. A postagem de lançamento do Google tem o enquadramento oficial.

API Gemini 3.8 Flash em resumo

Dois detalhes se destacam antes de você escrever o código. O nível de pensamento padrão é medium, não high como no Gemini 3 Pro. E os tokens de pensamento são faturados à taxa de saída na página de preços oficial, então o nível que você escolhe é uma decisão de custo tanto quanto de qualidade. O detalhamento de preços analisa os números por tarefa.

Passo 1: Obtenha uma chave de API no AI Studio

Abra o Google AI Studio, faça login com uma conta Google e crie uma chave de API na página de chaves. A chave funciona imediatamente no nível gratuito, com limites de taxa e a ressalva de que o Google diz que os dados do nível gratuito são "usados para melhorar nossos produtos". Vincule uma conta de faturamento para passar para o Nível 1 para limites de produção.

Exporte a chave em vez de colá-la no código:

export GEMINI_API_KEY="AIza..."

O SDK oficial do Python lê GEMINI_API_KEY do ambiente, então genai.Client() não precisa de argumentos. Instale-o com pip install google-genai.

Passo 2: Sua primeira chamada com a API de Interações

O Google agora trata a API de Interações como a forma primária de chamar modelos Gemini 3.x. A requisição é um objeto JSON: o modelo, uma input e um generation_config opcional onde o thinking_level reside.

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": "Explique o cache HTTP em 3 frases.",
    "generation_config": {"thinking_level": "medium"}
  }'

A resposta é uma lista de etapas de execução em vez de uma única mensagem. Pensamentos do modelo e chamadas de ferramentas aparecem como etapas, e a etapa final é model_output, que contém o texto. Em Python, o SDK simplifica isso para você:

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explique o cache HTTP em 3 frases.",
    generation_config={"thinking_level": "medium"},
)

print(interaction.output_text)

Deixe temperature, top_p e top_k de fora. A orientação do Google para cada modelo Gemini 3 é manter a temperatura em seu padrão de 1.0, porque reduzi-la "pode causar loops ou desempenho degradado". Se você copiou uma configuração de um modelo mais antigo, essa é a primeira linha a ser excluída.

Passo 3: Múltiplas interações com previous_interaction_id

A API de Interações mantém o estado da conversa no servidor por padrão. Para continuar uma conversa, envie o id da resposta anterior como previous_interaction_id junto com apenas a nova entrada do usuário. Você não reenvia o histórico.

follow_up = client.interactions.create(
    model="gemini-3.8-flash",
    input="Agora dê um exemplo de um cabeçalho Cache-Control.",
    previous_interaction_id=interaction.id,
)
print(follow_up.output_text)

Se suas regras de conformidade proibirem o armazenamento no lado do servidor, defina store: false. A compensação é que você gerencia o estado por si mesmo, incluindo o envio dos blocos de pensamento do modelo e das assinaturas de pensamento exatamente como os recebeu a cada turno. Essa é a mesma regra que atrapalha o uso de ferramentas, abordada no guia de chamada de funções para o 3.8 Flash.

Passo 4: O caminho legado generateContent

A maioria do código Gemini em produção ainda chama generateContent. O Google o chama de legado, mas ele "permanece totalmente suportado" sem data de descontinuação, então você não precisa reescrever nada hoje. Nosso guia da API Gemini 3.7 Flash cobriu apenas este caminho; o formato é idêntico para o 3.8 Flash, e a configuração de pensamento reside em um lugar diferente do que nas Interações.

Em generateContent, o nível vai sob generationConfig.thinkingConfig.thinkingLevel, em camelCase:

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

O equivalente em Python usa objetos de configuração tipados:

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Explique o cache HTTP em 3 frases.",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="low")
    ),
)
print(response.text)

Se você está vindo de uma configuração que usava thinking_budget como um inteiro, substitua-o pelo enum de string. candidate_count também foi removido no Gemini 3 e posteriores. A lista de verificação completa, com JSON de antes e depois para cada mudança, está no guia de migração do 3.7 para o 3.8 Flash.

Aqui está o mesmo conjunto de preocupações lado a lado, para que você possa traduzir entre as duas APIs sem reler ambas as documentações:

Passo 5: Streaming e leitura do custo de pensamento

Para interfaces de chat, troque o nome do método por streamGenerateContent e adicione ?alt=sse para obter eventos enviados pelo servidor, um pedaço parcial de candidates por evento:

curl -N "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"Liste três cabeçalhos de cache HTTP."}]}]}'

Com ou sem streaming, toda resposta generateContent termina com um objeto usageMetadata. Leia-o em cada chamada:

"usageMetadata": {
  "promptTokenCount": 12,
  "candidatesTokenCount": 84,
  "thoughtsTokenCount": 310,
  "totalTokenCount": 406
}

thoughtsTokenCount é o número a ser observado no 3.8 Flash. Os tokens de pensamento são faturados como tokens de saída a $3.75 por milhão durante o período de introdução, e o Google afirma que o modelo "pode usar mais tokens para maximizar o desempenho, especialmente em níveis de esforço mais altos". A Artificial Analysis mediu cerca de 48k tokens de saída por tarefa em sua execução de índice em high, 30% a mais que o 3.7 Flash, o que elevou o custo por tarefa de $0.40 para $0.58 com preços por token inalterados. Suas execuções em medium e low resultaram em $0.41 e $0.24 por tarefa. O guia de níveis de pensamento transforma esses números em uma estratégia por rota.

Para ver sobre o que o modelo raciocinou, adicione "includeThoughts": true dentro de thinkingConfig. Os resumos de pensamento retornam como partes marcadas com "thought": true; pule-as ao montar a resposta visível.

Erros que você encontrará na primeira hora

thinking_level: "minimal" falha na validação. O Gemini 3.8 Flash suporta apenas low, medium e high. Enviar minimal retorna 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), e a correção é uma mudança de uma palavra para low. Configurações 3.x mais antigas e trechos copiados são a fonte usual.

429 significa que você atingiu o limite do seu nível, não um bug. A página de limites de taxa explica os níveis: o nível gratuito é limitado por taxa, o Nível 1 é desbloqueado quando você vincula uma conta de faturamento, o Nível 2 precisa de $100 de gasto mais três dias, e o Nível 3 precisa de $1.000 mais 30 dias. Os números de solicitações por minuto e tokens por minuto por modelo são exibidos apenas na página de limites de taxa do AI Studio para sua conta, então verifique lá em vez de confiar em um número de uma postagem de blog. Em um 429, espere e tente novamente; em 429s repetidos com baixo volume, atualize o nível. Para trabalhos offline, a API Batch é a melhor correção: ela funciona com 50% de desconto ($0.375 / $1.875 por milhão de tokens durante o período de introdução) e tem seus próprios limites de tokens enfileirados de 3M no Nível 1, 400M no Nível 2 e 1B no Nível 3. O guia do modo batch do Gemini mostra o formato da requisição.

Faltando call_id em um resultado de função. Se você usa ferramentas, todo function_result (Interações) deve conter call_id e name no 3.8 Flash, e todo functionResponse legado deve conter o id correspondente mais name. Omitir um dos dois falha o turno.

Teste ambos os endpoints no Apidog antes de serem lançados

Uma vez que ambas as requisições funcionem do terminal, mova-as para um lugar onde toda a equipe possa executá-las. Baixe o Apidog, crie um projeto e adicione os dois endpoints acima como requisições salvas. Quatro hábitos que valem a pena:

• Mantenha a chave fora da requisição. Adicione GEMINI_API_KEY como uma variável de ambiente e faça referência a ela como {{GEMINI_API_KEY}} no cabeçalho x-goog-api-key. A requisição salva nunca contém o segredo, e alternar entre uma chave de nível gratuito e uma chave faturada é uma mudança de ambiente.
• Afirme o status e o uso de tokens. Adicione uma asserção de que o status é 200, então uma asserção de caminho JSON de que usageMetadata.thoughtsTokenCount permanece abaixo de um limite que você escolhe por prompt. O limite é o seu alarme de regressão de custo: se uma atualização de prompt ou uma mudança silenciosa do modelo aumentar os tokens de pensamento, o teste falha antes que a fatura chegue. O guia de teste de SSE cobre a variante de streaming, que o Apidog renderiza como um fluxo de eventos mesclado em vez de blocos brutos.
• Envie o mesmo prompt em todos os três níveis. Duplique a requisição com low, medium e high, e compare thoughtsTokenCount e tempo de resposta lado a lado. Isso dá a você números reais para seus prompts em vez de médias de índice.
• Agende-o. Transforme as requisições em um cenário de teste e execute-o em um cronograma, para que uma mudança no limite de taxa, uma mudança de validação como a remoção de minimal, ou um pico de token apareça em um relatório, e não em produção. Como agendar testes de API no Apidog detalha a configuração.

O Apidog não executa o modelo nem substitui o SDK. Ele oferece uma versão salva, compartilhável e asserível das chamadas HTTP, que é a parte que a maioria das equipes pula até que algo quebre.

Perguntas Frequentes (FAQ)

Qual endpoint os novos projetos devem usar? A API de Interações. O Google chama generateContent de legado, e ele ainda é totalmente suportado, mas novos recursos chegam primeiro nas Interações e o estado no lado do servidor torna o código multi-turno mais curto. Mantenha generateContent para serviços existentes até que você tenha um motivo para migrar.

Preciso de uma conta paga para chamar o Gemini 3.8 Flash? Não. Uma chave gratuita do AI Studio funciona, com limites de taxa e os termos de uso de dados do Google. O guia de uso gratuito lista o que o nível gratuito irá e não irá fornecer, incluindo o fato de que o aplicativo Gemini requer um plano AI Pro ou Ultra para o 3.8 Flash.

O 3.8 Flash é mais lento que o 3.7 Flash? Por token, não. Logan Kilpatrick do Google disse que é aproximadamente a mesma velocidade, e a Artificial Analysis mediu cerca de 300 tokens de saída por segundo. Por tarefa, leva mais tempo em high (2.5 minutos versus 2.2 em suas execuções) porque gera mais tokens.

Posso continuar chamando o Gemini 3.7 Flash? Sim. O Google diz que o 3.7 Flash "permanece totalmente suportado" e não publicou data de descontinuação. Se o gasto extra de tokens no 3.8 Flash não oferecer nenhum benefício para sua carga de trabalho, permanecer é uma escolha válida.

O 3.8 Flash suporta a Live API ou geração de imagens? Não. Ele produz apenas texto. Geração de áudio, geração de imagens e a Live API não são suportadas neste modelo.

Para onde ir em seguida

Você agora tem dois caminhos de chamada funcionais, um padrão de múltiplas interações e uma verificação de uso de tokens. A partir daqui, conecte ferramentas com o guia de chamada de funções, decida seus níveis por rota com a postagem sobre níveis de pensamento, e se você ainda está decidindo se deve migrar, a comparação do 3.8 vs 3.7 Flash apresenta o balanço. Mantenha o cenário do Apidog em execução para que o desvio de custo apareça como um teste falho.