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, e o descreve como “nosso modelo de trabalho mais inteligente”. A principal notícia para desenvolvedores: as pontuações de codificação agêntica deram um salto significativo (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 permanece inalterada. Se você já utiliza o Gemini, basta trocar um ID de modelo. Se não utiliza, este é o ponto de entrada mais barato que o Google já ofereceu para um modelo tão capaz.

Este guia é um início rápido prático. Você obterá uma chave de API, fará sua primeira chamada em cURL, a portará para Python e Node.js, fará o streaming de respostas, ajustará generationConfig e conectará tudo ao Apidog para que você possa iterar em prompts sem queimar tokens em um loop de código. As especificações do anúncio oficial: contexto de 1M de tokens, saída de 64k, entrada multimodal, chamada de função, pesquisa como ferramenta e uso de computador.

Se você construiu usando a geração anterior, o formato da requisição se mantém do nosso guia da API de Preview do Gemini 3 Flash; este artigo aborda tudo o que há de novo no fluxo de trabalho 3.7.

TL;DR

• O ID do modelo é gemini-3.7-flash. Endpoint: POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-flash:generateContent com o cabeçalho x-goog-api-key: <KEY>.
• O preço de lançamento é 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. A partir de 1º de janeiro de 2027, dobra para US$ 1.50 e US$ 7.50.
• Especificações: contexto de entrada de 1M de tokens, limite de saída de 64k de tokens. A entrada aceita texto, imagem, vídeo, áudio e PDF. A saída é texto.
• Diferenças de benchmark em relação ao 3.6 Flash: DeepSWE 49.0% para 65.3%, FrontierCode 34.4% para 43.6%, AutomationBench 17.0% para 30.4%, WebDev Arena Elo 1538 para 1588.
• Streaming utiliza :streamGenerateContent?alt=sse. O corpo da requisição mantém o esquema contents mais generationConfig do Google.
• Teste o endpoint no Apidog antes de escrever o código do aplicativo: importe a especificação, armazene a chave como uma variável de ambiente e observe os blocos SSE renderizarem ao vivo.

Para que o Gemini 3.7 Flash é bom

Os modelos Flash trocam um pouco de inteligência de pico por velocidade e preço, e o 3.7 estreita essa troca mais do que qualquer lançamento anterior. As diferenças de benchmark em relação ao 3.6 Flash são excepcionalmente grandes para um intervalo de três semanas: DeepSWE v1.1 saltou de 49.0% para 65.3%, FrontierCode 1.1 Main de 34.4% para 43.6%, e AutomationBench de 17.0% para 30.4%. O WebDev Arena Elo subiu 50 pontos, de 1538 para 1588.

Leia esses números como um sinal sobre o ajuste da carga de trabalho. Recorra ao 3.7 Flash quando:

• Você executa loops de agente. A pontuação do AutomationBench quase dobrou, e o Google diz que o modelo “pensa com mais diligência no planejamento de múltiplas etapas e chamadas de ferramentas”. Pipelines de agentes com muitas viradas curtas e intensivas em ferramentas são o caso de uso alvo.
• Você gera ou depura código. O Google afirma que o 3.7 é melhor na depuração e mais capaz de produzir código implantável na primeira tentativa. Os ganhos no DeepSWE e FrontierCode apoiam essa afirmação.
• Você processa documentos. O GDP.pdf saltou de 22.0% para 34.0%, e o PDF é um tipo de entrada de primeira classe. A recuperação de contexto longo também se mantém: 97.0% no teste de 128k-needle.
• Você precisa de entrada multimodal com um orçamento limitado. Texto, imagem, vídeo, áudio e PDF entram todos através do mesmo array contents.

Para uma descrição completa dos recursos, incluindo a pontuação Harvey LAB-AA de 90.7% no domínio legal e as salvaguardas CBRN e cibernéticas atualizadas, consulte as novidades no Gemini 3.7 Flash. Contexto que vale a pena saber: o Gemini 3.5 Pro ainda está atrasado, e a Axios relata que o Google está enviando atualizações Flash deliberadamente antes de seu próximo carro-chefe.

Obtenha uma chave de API

Dois caminhos, e eles não são equivalentes.

AI Studio (caminho rápido). Abra aistudio.google.com/apikey, clique em Obter chave de API, escolha um projeto do Google Cloud e copie a string. A chave funciona imediatamente com generativelanguage.googleapis.com, e o nível gratuito oferece cota suficiente para prototipagem. O Gemini 3.7 Flash está disponível em mais de 160 países.

Vertex AI (caminho de produção). Se sua infraestrutura reside no GCP, use o Vertex. A autenticação muda de uma chave de API para OAuth (contas de serviço ou tokens de curta duração), as chamadas são roteadas através de aiplatform.googleapis.com, e você obtém IAM, logs de auditoria e endpoints regionais. O ID do modelo e o corpo da requisição permanecem idênticos; apenas a URL e o mecanismo de autenticação mudam.

Prototípe no AI Studio, mude para o Vertex antes do tráfego de produção. De qualquer forma, exporte a chave uma vez:

export GEMINI_API_KEY="AIza..."

Nunca codifique a chave diretamente ou a passe como um parâmetro de consulta ?key= em produção; as strings de consulta acabam nos logs do servidor.

Endpoint e autenticação

O endpoint base para uma chamada síncrona:

POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-flash:generateContent

Streaming troca o sufixo do método e adiciona a flag SSE:

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

A autenticação é um cabeçalho: x-goog-api-key: $GEMINI_API_KEY. Essa é toda a negociação. Sem tokens de portador, sem esquema de assinatura, sem configuração de sessão.

Sua primeira requisição em cURL

Aqui está uma chamada completa e funcional:

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
    }
  }'

A resposta retorna um array candidates. Cada candidato contém um objeto content com parts (texto, ou chamadas de função se você declarou ferramentas) e um finishReason. A contagem de tokens reside em usageMetadata no nível superior; fique atento a esse bloco, pois os tokens de saída custam cinco vezes mais do que os tokens de entrada na taxa de lançamento.

Observe o esquema: o Google usa contents com role e parts, não o formato messages do OpenAI. Faça esse mapeamento corretamente primeiro se estiver portando de outro provedor.

Início rápido em Python

Instale ou atualize o SDK oficial:

pip install --upgrade google-generativeai

Uma chamada básica com uma instrução de sistema:

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)

A entrada multimodal reside no mesmo array contents. Para enviar um PDF, faça o upload através da API Files e referencie-o como uma parte:

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)

O ganho de benchmark do GDP.pdf (22.0% para 34.0%) aparece exatamente nesta carga de trabalho: extração estruturada de documentos do mundo real desorganizados.

Início rápido em Node.js

O SDK do Node é @google/generative-ai e espelha o formato do Python:

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()));

A linha responseSchema importa mais do que parece. Ela força o candidato a um objeto analisável, de modo que o código downstream nunca toque em texto de formato livre. Combine-o com responseMimeType: "application/json" ou ele será ignorado.

Streaming

Para UIs de chat e qualquer coisa voltada para o usuário, use streaming. Em Python, adicione stream=True:

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)

Via HTTP puro, acesse :streamGenerateContent?alt=sse e analise eventos enviados pelo servidor. Cada linha data: transporta um payload parcial de candidates; o bloco final inclui usageMetadata, então a contabilidade de tokens só é precisa após o fechamento do stream.

Ajustando generationConfig

Os parâmetros que você mais manipulará, em ordem aproximada de impacto:

Os tokens de saída custam US$ 3.75 por milhão na taxa de lançamento e US$ 7.50 a partir de janeiro de 2027, então limite a saída ao que seu caso de uso precisa, e não ao teto de 64k. O cálculo completo dos tokens, com exemplos trabalhados por carga de trabalho, está em nossa análise de preços do Gemini 3.7 Flash.

Além de generationConfig, o corpo da requisição também aceita tools (declarações de função, pesquisa como ferramenta, uso de computador) e toolConfig para forçar chamadas de ferramenta. O uso de ferramentas é onde o 3.7 Flash mais melhorou, e merece um guia próprio: consulte o tutorial de chamada de função do Gemini 3.7 Flash para declarações, chamadas paralelas e o padrão de loop de resposta.

Teste o endpoint no Apidog antes de escrever o código do aplicativo

A iteração de prompts dentro de um script Python é lenta e cara: edite, execute novamente, role, repita, e cada ciclo cobra tokens. O loop mais rápido é fixar o formato da requisição em um cliente API primeiro, e então portar para o código quando as respostas estiverem corretas.

O Apidog lida com o esquema de requisição do Gemini nativamente. A configuração:

1. Crie um projeto e importe a especificação OpenAPI da Generative Language API dos documentos da API do Google. A coleção chega pré-nomeada, então generateContent está a uma busca de distância.
2. Adicione uma variável de ambiente chamada GEMINI_API_KEY e vincule-a ao cabeçalho x-goog-api-key no nível do ambiente. Toda requisição a herdará, e a chave nunca aparecerá no corpo de uma requisição salva.
3. Armazene o ID do modelo como uma variável definida para gemini-3.7-flash. Quando você quiser fazer um teste A/B contra gemini-3.6-flash, você muda uma variável em vez de editar URLs em uma dezena de requisições salvas.
4. Construa o array contents no editor visual de JSON. Partes aninhadas são renderizadas de forma limpa, e a validação de esquema detecta um corpo malformado antes que você gaste um único token em um erro 400.
5. Acesse o endpoint de streaming. O Apidog renderiza os blocos SSE ao vivo, então você vê a resposta se montar exatamente da forma que seu SDK a verá, incluindo a latência.
6. Salve boas respostas como exemplos. Execuções de teste posteriores usarão o fixture em vez da API real. Este é o maior economizador de tokens em todo o fluxo de trabalho.

Uma vez salvas as requisições, encadeie-as em cenários de teste com asserções em finishReason, esquema de resposta e contagens de tokens de usageMetadata. Isso transforma um teste de fumaça manual em uma suíte de regressão que você pode executar a cada alteração de prompt; o mesmo padrão que as equipes de QA usam é abordado em nosso guia de teste de API para engenheiros de QA.

Tratamento de erros e limites de taxa

Os erros do Gemini retornam um objeto error de nível superior com code, status e message. Os que você encontrará:

Três hábitos mantêm a produção estável:

• Encapsule cada chamada em um auxiliar de retentativa que lide com 429 e 5xx com backoff exponencial com jitter. Os SDKs tentam novamente algumas vezes por conta própria, mas um wrapper fino oferece registro e disjuntor que você controla.
• Não invente números de limite de taxa. Os limites variam por nível e mudam com o tempo; leia os valores atualizados na página de preços e limites da API Gemini e alerte ao atingir 80% da cota.
• Fixe o ID do modelo atrás de uma variável de ambiente. Se uma alteração de comportamento do 3.7 quebrar um prompt, reverter para gemini-3.6-flash se torna uma alteração de configuração em vez de um deploy.

FAQ

O Gemini 3.7 Flash é gratuito para usar?

O AI Studio oferece um nível gratuito com cota diária suficiente para prototipagem, e a taxa de lançamento paga é de US$ 0.75 por 1M de tokens de entrada até 31 de dezembro de 2026. Se você quiser estender ainda mais o caminho sem custo, nosso guia para acesso gratuito à API Gemini aborda os níveis e seus limites.

Qual a diferença entre chamá-lo via AI Studio e Vertex AI?

Mesmo modelo, mesmo corpo de requisição, encanamento diferente. O AI Studio usa uma chave de API com generativelanguage.googleapis.com; o Vertex usa OAuth com aiplatform.googleapis.com e adiciona IAM, log de auditoria e endpoints regionais. Comece no AI Studio, e migre para o Vertex quando o tráfego se tornar real.

Posso enviar imagens, áudio e PDFs para o Gemini 3.7 Flash?

Sim. A entrada é multimodal: texto, imagem, vídeo, áudio e PDF viajam como partes no array contents, inline como base64 ou por referência através da API Files. A saída é somente texto.

Qual o tamanho da janela de contexto e o limite de saída?

1M de tokens de entrada, 64k de tokens de saída. A pontuação de recuperação de 97.0% no teste de 128k-needle sugere que a recuperação de contexto longo é confiável muito além do que a maioria dos aplicativos precisa, mas o fatiamento de entradas longas ainda economiza dinheiro, já que cada token de entrada é cobrado.

Devo fazer upgrade do Gemini 3.6 Flash?

Para cargas de trabalho de agente e codificação, as diferenças nos benchmarks são grandes o suficiente para que a resposta seja geralmente sim, e a troca do ID do modelo é uma única linha. As diferenças de comportamento que valem a pena testar por regressão antes de direcionar o tráfego de produção são abordadas no guia de migração do 3.6 para o 3.7 Flash.

Onde o 3.7 Flash se encaixa na sua stack

O Gemini 3.7 Flash é um lançamento raro onde o preço diminuiu enquanto a capacidade aumentou. Até o final de 2026, você estará pagando metade da taxa de lançamento do 3.6 Flash por um modelo que pontua 16 pontos a mais no DeepSWE e quase o dobro no AutomationBench. O padrão sensato: direcione loops de agente, tarefas de código e extração de documentos para o 3.7 Flash agora, tenha em mente a janela da taxa de lançamento para o planejamento orçamentário e mantenha um caminho de reversão para o 3.6 por trás de uma variável de ambiente.

Comece com a chamada cURL acima, confirme o formato da resposta e, em seguida, mova a requisição para um cliente API antes de escrever o código do aplicativo. Baixe o Apidog para importar a especificação do Gemini, vincule sua chave uma vez e teste requisições síncronas, de streaming e de chamada de ferramenta de um único workspace. Quando o prompt estiver correto, a portagem para Python ou Node leva minutos porque você já sabe como é o tráfego de rede.