DEV Community

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

Posted on Originally published at apidog.com

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

Gemini 3.8 Flash na API: integração, raciocínio, streaming e custos

O Google lançou o Gemini 3.8 Flash em 2 de setembro de 2026. O ID da API é gemini-3.8-flash, sem sufixo de pré-visualização. O modelo mantém o preço introdutório do 3.7 Flash — US$ 0,75 por milhão de tokens de entrada e US$ 3,75 por milhão de tokens de saída — até 31 de dezembro de 2026. Segundo o Google, ele “trabalha mais”: executa mais etapas de raciocínio e chama ferramentas com mais frequência em tarefas complexas, o que pode aumentar o consumo de tokens.

Experimente o Apidog hoje

Este guia mostra como obter uma chave no AI Studio, fazer chamadas pela API de Interações, continuar conversas, usar o endpoint legado generateContent, configurar thinking_level, fazer streaming e monitorar thoughtsTokenCount. Todas as chamadas usam HTTP e JSON, para que você possa testá-las no Apidog antes de colocá-las em produção.

Para benchmarks e mudanças do modelo, consulte o que é o Gemini 3.8 Flash e a postagem de lançamento do Google.

Gemini 3.8 Flash em resumo

Item Valor
ID do modelo gemini-3.8-flash
Endpoint primário POST /v1beta/interactions
Endpoint legado POST /v1beta/models/gemini-3.8-flash:generateContent
Autenticação Cabeçalho x-goog-api-key
Contexto / saída 1.048.576 tokens de entrada / 65.536 tokens de saída
Entradas Texto, imagem, vídeo, áudio e PDF
Saída Apenas texto
Níveis de pensamento low, medium (padrão) e high
minimal Não suportado; retorna erro
Preço introdutório até 31/12/2026 US$ 0,75 / US$ 3,75 por 1 milhão de tokens
Preço a partir de 01/01/2027 US$ 1,50 / US$ 7,50 por 1 milhão de tokens

O nível padrão é medium, não high como no Gemini 3 Pro. Tokens de pensamento são cobrados como tokens de saída, portanto o nível escolhido afeta tanto a qualidade quanto o custo. Consulte a página oficial de preços e o detalhamento de preços do Gemini 3.8 Flash.

Passo 1: obtenha uma chave de API

Abra o Google AI Studio, faça login e crie uma chave na página de chaves.

A chave funciona imediatamente no nível gratuito, com limites de taxa. O Google informa que dados do nível gratuito podem ser “usados para melhorar nossos produtos”. Para limites de produção, vincule uma conta de faturamento e passe para o Nível 1.

Mantenha a chave fora do código:

export GEMINI_API_KEY="AIza..."
Enter fullscreen mode Exit fullscreen mode

O SDK oficial do Python lê GEMINI_API_KEY automaticamente:

pip install google-genai
Enter fullscreen mode Exit fullscreen mode

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

A API de Interações é atualmente a forma primária de chamar modelos Gemini 3.x. O campo thinking_level fica dentro de generation_config.

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-[REDACTED CREDENTIAL] \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Explique o cache HTTP em 3 frases.",
    "generation_config": {"thinking_level": "medium"}
  }'
Enter fullscreen mode Exit fullscreen mode

A resposta contém uma lista de etapas de execução. Pensamentos e chamadas de ferramentas aparecem como etapas; a etapa final é model_output.

Com Python:

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)
Enter fullscreen mode Exit fullscreen mode

Não defina temperature, top_p ou top_k sem uma razão específica. A recomendação do Google para os modelos Gemini 3 é manter a temperatura padrão em 1.0, pois reduzi-la pode causar loops ou degradar o desempenho.

Passo 3: continue a conversa

A API de Interações mantém o estado no servidor por padrão. Para continuar, envie o ID da interação anterior e apenas a nova entrada:

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)
Enter fullscreen mode Exit fullscreen mode

Se a conformidade exigir que o estado não seja armazenado no servidor, use store: false. Nesse caso, você deverá gerenciar o histórico, incluindo os blocos e as assinaturas de pensamento exatamente como foram recebidos em cada turno. Isso também afeta o uso de ferramentas; veja o guia de chamada de funções do Gemini 3.8 Flash.

Passo 4: use o endpoint legado generateContent

A maior parte do código Gemini em produção ainda usa generateContent. O Google o classifica como legado, mas afirma que ele permanece totalmente suportado e não publicou uma data de descontinuação.

O formato é o mesmo do Gemini 3.7 Flash. A diferença principal é o local da configuração de pensamento: em generateContent, use generationConfig.thinkingConfig.thinkingLevel.

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

Com o SDK Python:

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)
Enter fullscreen mode Exit fullscreen mode

Se sua configuração usava thinking_budget como inteiro, substitua-o pelo enum de string. candidate_count também foi removido no Gemini 3 e posteriores. O guia de migração do Gemini 3.7 para o 3.8 Flash traz exemplos de JSON antes e depois. Para comparar com o caminho anterior, consulte o guia da API Gemini 3.7 Flash.

Interações versus generateContent

Preocupação API de Interações generateContent legado
Nível de pensamento generation_config.thinking_level generationConfig.thinkingConfig.thinkingLevel
Estado da conversa previous_interaction_id no servidor Reenvie o array contents completo
Resultado de ferramenta function_result com call_id e name functionResponse com id e name
Texto final Etapa model_output ou output_text no SDK candidates[0].content.parts[].text
Assinaturas de pensamento Gerenciadas automaticamente, exceto com store: false Reenvie cada parte exatamente como recebida

Passo 5: faça streaming e monitore o custo

Para interfaces de chat, use streamGenerateContent com ?alt=sse:

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

Com ou sem streaming, as respostas terminam com usageMetadata:

{
  "usageMetadata": {
    "promptTokenCount": 12,
    "candidatesTokenCount": 84,
    "thoughtsTokenCount": 310,
    "totalTokenCount": 406
  }
}
Enter fullscreen mode Exit fullscreen mode

Monitore thoughtsTokenCount. Durante o período introdutório, esses tokens são cobrados como saída a US$ 3,75 por milhão. O Google afirma que o modelo pode usar mais tokens para maximizar o desempenho, especialmente em níveis de esforço altos.

A Artificial Analysis mediu cerca de 48 mil tokens de saída por tarefa no nível high, aproximadamente 30% a mais que o 3.7 Flash. Com os preços atuais, isso elevou o custo por tarefa de US$ 0,40 para US$ 0,58. Nas execuções avaliadas, medium custou US$ 0,41 por tarefa e low, US$ 0,24. O guia de níveis de pensamento ajuda a escolher uma estratégia por rota.

Para receber resumos do raciocínio, habilite includeThoughts dentro de thinkingConfig:

{
  "thinkingConfig": {
    "thinkingLevel": "medium",
    "includeThoughts": true
  }
}
Enter fullscreen mode Exit fullscreen mode

Os resumos retornam como partes com "thought": true. Ignore essas partes ao montar a resposta exibida ao usuário.

Erros comuns

minimal retorna 400 INVALID_ARGUMENT

O Gemini 3.8 Flash aceita apenas low, medium e high. Enviar:

{
  "thinking_level": "minimal"
}
Enter fullscreen mode Exit fullscreen mode

retorna:

Thinking level MINIMAL is not supported for this model.
Please retry with other thinking level.
Enter fullscreen mode Exit fullscreen mode

A correção é trocar minimal por low.

429 indica limite de uso

Um 429 normalmente significa que você atingiu o limite do seu nível, não que a requisição está incorreta. Os níveis são:

  • Nível gratuito: limites de taxa;
  • Nível 1: disponível após vincular uma conta de faturamento;
  • Nível 2: exige US$ 100 em gastos e três dias;
  • Nível 3: exige US$ 1.000 em gastos e 30 dias.

As solicitações por minuto e os tokens por minuto dependem da conta e aparecem na página de limites do AI Studio. Consulte a página oficial de limites de taxa em vez de usar números antigos de posts.

Em um 429, aguarde e tente novamente. Se os erros persistirem mesmo com baixo volume, atualize o nível. Para trabalhos offline, use a API Batch: ela oferece 50% de desconto, com preço introdutório de US$ 0,375 por milhão de tokens de entrada e US$ 1,875 por milhão de tokens de saída. Os limites de tokens enfileirados são 3 milhões no Nível 1, 400 milhões no Nível 2 e 1 bilhão no Nível 3. Veja o guia do modo Batch do Gemini.

Resultado de função sem call_id

Ao usar ferramentas, cada function_result da API de Interações precisa conter call_id e name. No endpoint legado, functionResponse precisa conter o id correspondente e name. Omitir qualquer um desses campos faz o turno falhar.

Teste os endpoints no Apidog

Depois de validar as requisições no terminal, baixe o Apidog, crie um projeto e salve os dois endpoints.

1. Mantenha a chave fora da requisição

Crie GEMINI_API_KEY como variável de ambiente e use:

{{GEMINI_API_KEY}}
Enter fullscreen mode Exit fullscreen mode

no cabeçalho x-goog-api-key. Assim, a requisição salva não contém o segredo e você pode alternar entre uma chave gratuita e uma chave faturada por ambiente.

2. Teste status e consumo

Adicione:

  1. Uma asserção para confirmar status 200;
  2. Uma asserção JSON para garantir que usageMetadata.thoughtsTokenCount permaneça abaixo de um limite definido por prompt.

Esse limite funciona como um alarme de regressão de custo. Uma alteração no prompt ou no comportamento do modelo fará o teste falhar antes de afetar a fatura.

Para streaming, consulte o guia de testes de APIs SSE. O Apidog renderiza o fluxo como eventos mesclados, em vez de exibir os blocos brutos.

3. Compare os níveis de pensamento

Duplique a requisição usando low, medium e high. Envie o mesmo prompt nos três casos e compare:

  • thoughtsTokenCount;
  • tempo de resposta;
  • qualidade do resultado;
  • custo estimado.

Assim, você obtém dados reais para seus prompts, e não apenas médias de benchmarks.

4. Agende os testes

Transforme as requisições em um cenário de teste e agende execuções periódicas. Isso ajuda a detectar:

  • mudanças nos limites de taxa;
  • alterações de validação, como a remoção de minimal;
  • aumento inesperado de tokens;
  • regressões de latência.

Veja como agendar testes de API no Apidog.

O Apidog não executa o modelo nem substitui o SDK. Ele fornece uma versão salva, compartilhável e validável das chamadas HTTP — justamente a parte que muitas equipes só automatizam depois de uma falha em produção.

Perguntas frequentes

Qual endpoint novos projetos devem usar?

A API de Interações. O Google chama generateContent de legado, embora ele continue totalmente suportado. As novidades chegam primeiro nas Interações, e o estado mantido no servidor reduz o código necessário para conversas com vários turnos.

Mantenha generateContent em serviços existentes até ter um motivo concreto para migrar.

Preciso de uma conta paga?

Não. Uma chave gratuita do AI Studio funciona, sujeita a limites de taxa e aos termos de uso de dados do Google. O guia para usar o Gemini 3.8 Flash gratuitamente explica as limitações do nível gratuito, incluindo o fato de que o aplicativo Gemini exige 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, afirmou que a velocidade é aproximadamente a mesma, e a Artificial Analysis mediu cerca de 300 tokens de saída por segundo.

Por tarefa, o nível high leva mais tempo porque gera mais tokens: aproximadamente 2,5 minutos contra 2,2 minutos nas execuções avaliadas.

Posso continuar usando o Gemini 3.7 Flash?

Sim. O Google afirma que o 3.7 Flash permanece totalmente suportado e não publicou uma data de descontinuação. Se o consumo extra do 3.8 Flash não trouxer benefícios para sua carga de trabalho, continuar no 3.7 é uma opção válida.

Veja a comparação entre Gemini 3.8 e 3.7 Flash.

O 3.8 Flash suporta Live API ou geração de imagens?

Não. O modelo produz apenas texto. Geração de áudio, geração de imagens e Live API não são suportadas.

Próximos passos

Agora você tem:

  • uma chamada funcional pela API de Interações;
  • uma alternativa legada com generateContent;
  • um padrão para conversas com vários turnos;
  • streaming via SSE;
  • monitoramento de thoughtsTokenCount;
  • testes automatizados no Apidog.

A seguir, conecte ferramentas usando o guia de chamada de funções, escolha níveis por rota com o guia de níveis de pensamento e mantenha o cenário do Apidog agendado para transformar desvios de custo em testes falhos, não em surpresas na produção.

Top comments (0)