DEV Community

Cover image for Como usar a Gemini 3.7 Flash API?
Lucas
Lucas

Posted on Originally published at apidog.com

Como usar a Gemini 3.7 Flash API?

O Google lançou o Gemini 3.7 Flash em 13 de agosto de 2026, três semanas após o 3.6 Flash, descrevendo-o como “nosso modelo de trabalho mais inteligente”. Para desenvolvedores, a atualização é direta: os benchmarks de codificação agêntica melhoraram significativamente — DeepSWE v1.1 passou de 49,0% para 65,3% —, o preço de lançamento é metade do valor inicial do 3.6 Flash e a superfície da API não mudou. Se você já usa Gemini, a migração começa trocando o ID do modelo.

Experimente o Apidog hoje

Este guia mostra como obter uma chave de API, testar uma chamada com cURL, portar a integração para Python e Node.js, usar streaming, ajustar generationConfig e validar prompts no Apidog. Segundo o anúncio oficial, o modelo oferece contexto de 1M de tokens, saída de até 64k tokens, entrada multimodal, chamada de função, pesquisa como ferramenta e uso de computador.

Se você já desenvolveu com a geração anterior, o formato da requisição continua igual ao do guia da API Preview do Gemini 3 Flash. Aqui, o foco é no fluxo de trabalho do 3.7.

TL;DR

  • Modelo: gemini-3.7-flash
  • Endpoint síncrono: POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-flash:generateContent
  • Autenticação: cabeçalho x-goog-api-key: <KEY>
  • Preço de lançamento: 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. A partir de 1º de janeiro de 2027, os valores passam para US$ 1,50 e US$ 7,50.
  • Limites: 1M de tokens de contexto e 64k tokens de saída.
  • Entrada: texto, imagem, vídeo, áudio e PDF.
  • Streaming: use :streamGenerateContent?alt=sse.
  • Migração do 3.6: troque o ID do modelo e execute testes de regressão nos prompts.
  • Teste antes de codificar: valide o endpoint no Apidog, armazene a chave como variável de ambiente e acompanhe eventos SSE ao vivo.

Quando usar o Gemini 3.7 Flash

Os modelos Flash priorizam velocidade e custo, mas o 3.7 reduziu bastante a diferença em capacidade. Em comparação com o Gemini 3.6 Flash:

  • DeepSWE v1.1: 49,0% → 65,3%
  • FrontierCode 1.1 Main: 34,4% → 43,6%
  • AutomationBench: 17,0% → 30,4%
  • WebDev Arena Elo: 1538 → 1588

Benchmarks do Gemini 3.7 Flash

Use o 3.7 Flash especialmente quando:

  • Você executa loops de agentes: o ganho no AutomationBench indica melhor planejamento em múltiplas etapas e chamadas de ferramentas.
  • Você gera ou revisa código: os resultados em DeepSWE e FrontierCode favorecem tarefas de depuração, revisão e geração de código.
  • Você processa documentos: o GDP.pdf passou de 22,0% para 34,0%, e PDFs são aceitos como entrada de primeira classe.
  • Você precisa de multimodalidade com orçamento controlado: texto, imagens, vídeos, áudios e PDFs usam o mesmo array contents.

Para mais contexto sobre recursos, benchmark Harvey LAB-AA e salvaguardas atualizadas, consulte as novidades do Gemini 3.7 Flash. A Axios relata que o Google está entregando atualizações Flash antes do próximo modelo principal.

Obtenha uma chave de API

Há dois caminhos principais.

AI Studio: prototipagem rápida

  1. Abra aistudio.google.com/apikey.
  2. Clique em Obter chave de API.
  3. Selecione um projeto do Google Cloud.
  4. Copie a chave gerada.

A chave funciona com generativelanguage.googleapis.com. O AI Studio oferece um nível gratuito para prototipagem, e o Gemini 3.7 Flash está disponível em mais de 160 países.

Vertex AI: uso em produção no GCP

Use Vertex AI se sua infraestrutura já está no Google Cloud. Nesse caso:

  • a autenticação usa OAuth, contas de serviço ou tokens de curta duração;
  • as chamadas usam aiplatform.googleapis.com;
  • você obtém IAM, logs de auditoria e endpoints regionais.

O ID do modelo e o corpo da requisição permanecem iguais; mudam a URL e a autenticação.

Exporte a chave localmente:

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

Nunca inclua a chave diretamente no código ou como ?key= em URLs de produção. Strings de consulta podem aparecer em logs de servidor.

Endpoint e autenticação

Para uma chamada síncrona:

POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-flash:generateContent
Enter fullscreen mode Exit fullscreen mode

Para streaming com Server-Sent Events:

POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-flash:streamGenerateContent?alt=sse
Enter fullscreen mode Exit fullscreen mode

Envie a chave no cabeçalho:

x-goog-api-key: $GEMINI_API_KEY
Enter fullscreen mode Exit fullscreen mode

Faça sua primeira chamada com cURL

Crie uma requisição mínima para confirmar credenciais, endpoint e formato de resposta:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "Review this SQL for injection risk: SELECT * FROM orders WHERE id = ${orderId}"
      }]
    }],
    "generationConfig": {
      "temperature": 0.3,
      "maxOutputTokens": 1024
    }
  }'
Enter fullscreen mode Exit fullscreen mode

A resposta inclui:

  • candidates: candidatos gerados;
  • candidates[].content.parts: texto ou chamadas de função;
  • candidates[].finishReason: motivo de término;
  • usageMetadata: contagem de tokens.

Observe que a API do Google usa contents, role e parts, e não o formato messages de provedores compatíveis com OpenAI.

Início rápido em Python

Instale ou atualize o SDK:

pip install --upgrade google-generativeai
Enter fullscreen mode Exit fullscreen mode

Faça uma chamada com instrução de sistema e configuração de geração:

import os
import google.generativeai as genai

genai.configure(api_key=os.environ["GEMINI_API_KEY"])

model = genai.GenerativeModel(
    model_name="gemini-3.7-flash",
    system_instruction=(
        "You are a code reviewer. "
        "Flag issues as blocking or non-blocking."
    ),
    generation_config={
        "temperature": 0.3,
        "max_output_tokens": 2048,
    },
)

response = model.generate_content(
    "Review this Flask route for security issues:\n\n"
    "@app.route('/user/<id>')\n"
    "def get_user(id):\n"
    "    return db.execute(f'SELECT * FROM users WHERE id = {id}')"
)

print(response.text)
print("input tokens:", response.usage_metadata.prompt_token_count)
print("output tokens:", response.usage_metadata.candidates_token_count)
Enter fullscreen mode Exit fullscreen mode

Envie um PDF

A entrada multimodal usa o mesmo fluxo. Faça upload do arquivo e passe a referência como parte do conteúdo:

invoice = genai.upload_file("q3-invoice.pdf")

response = model.generate_content([
    invoice,
    "Extract the invoice number, total, and due date as JSON.",
])

print(response.text)
Enter fullscreen mode Exit fullscreen mode

Esse é um caso alinhado ao ganho do modelo no benchmark GDP.pdf: extração estruturada a partir de documentos reais.

Início rápido em Node.js

Instale o SDK:

npm install @google/generative-ai
Enter fullscreen mode Exit fullscreen mode

Use responseMimeType e responseSchema para obter JSON estruturado:

import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);

const model = genAI.getGenerativeModel({
  model: "gemini-3.7-flash",
  generationConfig: {
    temperature: 0.3,
    maxOutputTokens: 2048,
    responseMimeType: "application/json",
    responseSchema: {
      type: "object",
      properties: {
        severity: {
          type: "string",
          enum: ["blocking", "non-blocking"],
        },
        issues: {
          type: "array",
          items: { type: "string" },
        },
      },
      required: ["severity", "issues"],
    },
  },
});

const result = await model.generateContent(
  "Review this Express handler: app.get('/search', (req, res) => res.send(eval(req.query.q)))"
);

console.log(JSON.parse(result.response.text()));
Enter fullscreen mode Exit fullscreen mode

responseSchema só deve ser usado junto com:

responseMimeType: "application/json"
Enter fullscreen mode Exit fullscreen mode

Assim, o código downstream recebe uma estrutura analisável em vez de texto livre.

Use streaming para respostas progressivas

Para interfaces de chat e recursos voltados ao usuário, use streaming.

Em Python:

stream = model.generate_content(
    "Explain the N+1 query problem with a concrete ORM example.",
    stream=True,
)

for chunk in stream:
    if chunk.text:
        print(chunk.text, end="", flush=True)
Enter fullscreen mode Exit fullscreen mode

Em HTTP puro, use o endpoint:

:streamGenerateContent?alt=sse
Enter fullscreen mode Exit fullscreen mode

Cada linha data: contém um payload parcial com candidates. O bloco final inclui usageMetadata, portanto a contagem completa de tokens só está disponível quando o stream termina.

Ajuste generationConfig

Estes são os parâmetros mais úteis no dia a dia:

Parâmetro Tipo Uso prático
maxOutputTokens integer Limita a saída, até 64k tokens. É a principal alavanca de custo.
temperature number Vai de 0 a 2. Use 0,2–0,4 para código e extração; 0,7+ para conteúdo criativo.
responseMimeType string Use application/json para saída JSON.
responseSchema object Define uma estrutura rígida quando combinado com JSON.
topP number Controla a amostragem nucleus. Mantenha o padrão salvo se estiver ajustando intencionalmente.
stopSequences array Interrompe a geração em delimitadores específicos.

Os tokens de saída custam US$ 3,75 por milhão durante a taxa de lançamento e US$ 7,50 a partir de janeiro de 2027. Defina maxOutputTokens com base no tamanho realmente necessário para a resposta. Veja exemplos de cálculo em nossa análise de preços do Gemini 3.7 Flash.

Além de generationConfig, a requisição aceita tools e toolConfig para declarações de funções, pesquisa como ferramenta e uso de computador. Para implementar esse fluxo, consulte o tutorial de chamada de função do Gemini 3.7 Flash.

Teste o endpoint no Apidog antes de integrar ao app

Iterar prompts apenas em scripts pode ser lento e caro: editar, executar, inspecionar e repetir consome tokens a cada ciclo. Primeiro, fixe o contrato da requisição em um cliente de API; depois, leve a versão validada para o SDK.

No Apidog, siga este fluxo:

  1. Crie um projeto e importe a especificação OpenAPI da Generative Language API a partir da documentação da API Gemini.
  2. Crie a variável de ambiente GEMINI_API_KEY.
  3. Vincule a variável ao cabeçalho x-goog-api-key.
  4. Crie uma variável para o modelo, como GEMINI_MODEL=gemini-3.7-flash.
  5. Monte o array contents no editor JSON e valide o corpo antes do envio.
  6. Teste o endpoint SSE para acompanhar blocos de streaming em tempo real.
  7. Salve respostas válidas como exemplos para usar fixtures em testes posteriores, sem chamar a API real.

Depois, transforme os casos salvos em cenários de teste com asserções para:

  • finishReason;
  • formato da resposta;
  • campos obrigatórios;
  • contagens em usageMetadata.

Esse padrão permite executar regressões sempre que um prompt for alterado. Para expandir a estratégia, veja o guia de testes de API para engenheiros de QA.

Tratamento de erros e limites de taxa

A API retorna um objeto error de nível superior com code, status e message.

Código Status Causa comum Ação recomendada
400 INVALID_ARGUMENT Corpo malformado, papel incorreto ou contents vazio. Valide o JSON antes de enviar.
401 UNAUTHENTICATED Chave ausente ou revogada. Reexporte GEMINI_API_KEY e valide a chave no AI Studio.
403 PERMISSION_DENIED Projeto sem acesso ou faturamento. Verifique o projeto e o status de faturamento.
429 RESOURCE_EXHAUSTED Limite de taxa ou cota diária atingida. Use espera com jitter, agrupe chamadas ou altere o plano.
500 INTERNAL Falha temporária do servidor. Tente novamente com backoff exponencial.
503 UNAVAILABLE Serviço sobrecarregado. Tente novamente após alguns segundos; no Vertex, tente outra região.

Implemente retentativas para 429 e erros 5xx:

import random
import time

RETRYABLE_STATUS_CODES = {429, 500, 503}

def retry_with_backoff(call, max_attempts=5):
    for attempt in range(max_attempts):
        try:
            return call()
        except Exception:
            if attempt == max_attempts - 1:
                raise

            delay = min(2 ** attempt, 30) + random.uniform(0, 1)
            time.sleep(delay)
Enter fullscreen mode Exit fullscreen mode

Também vale seguir três práticas:

  • monitore o consumo e alerte ao atingir 80% da cota;
  • consulte os valores atuais na página de preços e limites da API Gemini, sem fixar números no código;
  • mantenha o ID do modelo em variável de ambiente para permitir rollback rápido.

Exemplo:

export GEMINI_MODEL="gemini-3.7-flash"
Enter fullscreen mode Exit fullscreen mode

FAQ

O Gemini 3.7 Flash é gratuito?

O AI Studio oferece um nível gratuito com cota diária para prototipagem. A tarifa de lançamento é de US$ 0,75 por 1M de tokens de entrada até 31 de dezembro de 2026. Para entender os níveis disponíveis, consulte o guia de acesso gratuito à API Gemini.

Qual é a diferença entre AI Studio e Vertex AI?

O modelo e o corpo da requisição são os mesmos. A diferença está na infraestrutura:

  • AI Studio: chave de API e generativelanguage.googleapis.com;
  • Vertex AI: OAuth, aiplatform.googleapis.com, IAM, logs de auditoria e endpoints regionais.

Comece no AI Studio para prototipar e migre para Vertex AI antes de direcionar tráfego de produção.

Posso enviar imagens, áudio e PDFs?

Sim. Texto, imagem, vídeo, áudio e PDF podem ser enviados no array contents, inline como base64 ou por referência com a API Files. A saída é texto.

Qual é o limite de contexto e saída?

O modelo aceita até 1M de tokens de entrada e gera até 64k tokens de saída. Mesmo com uma janela longa, dividir entradas grandes pode reduzir custo, pois tokens de entrada também são cobrados.

Devo migrar do Gemini 3.6 Flash?

Para cargas de trabalho de agentes e código, os ganhos de benchmark justificam testar a migração. A alteração inicial é apenas:

gemini-3.6-flash → gemini-3.7-flash
Enter fullscreen mode Exit fullscreen mode

Antes de enviar tráfego de produção, execute testes de regressão nos prompts. Consulte o guia de migração do Gemini 3.6 para o 3.7 Flash.

Onde o Gemini 3.7 Flash se encaixa na sua stack

O Gemini 3.7 Flash combina custo menor com ganhos relevantes em agentes, código e processamento de documentos. O padrão de adoção mais seguro é:

  1. comece pela chamada cURL;
  2. valide a estrutura de contents e a resposta;
  3. teste prompts e streaming em um cliente de API;
  4. mova a integração validada para Python ou Node.js;
  5. mantenha o modelo configurável por variável de ambiente para rollback.

Para importar a especificação do Gemini, armazenar a chave uma única vez e testar requisições síncronas, streaming e ferramentas no mesmo workspace, baixe o Apidog.

Top comments (0)