Como usar a Gemini 3.6 Flash API

Você chama o Gemini 3.6 Flash com o ID do modelo gemini-3.6-flash pela API Gemini do Google. Essa é a essência. O Google lançou a atualização Flash em 21 de julho de 2026, e o 3.6 Flash é a camada principal: saída mais barata que o 3.5 Flash, uma janela de contexto de 1M de tokens e entradas de texto, imagem, vídeo, áudio e PDF. Este guia leva você do zero a uma requisição testada. Você obterá uma chave, fará sua primeira chamada em curl e Python, aprenderá os parâmetros importantes e configurará um teste de regressão para que a chamada continue funcionando depois de implementá-la.

O que você precisa antes de começar

Três coisas, e nenhuma delas custa dinheiro para começar.

• Uma conta Google. É assim que você faz login para obter uma chave.
• Uma chave de API Gemini. É gratuita no Google AI Studio, e a próxima seção aborda isso.
• Uma maneira de enviar uma requisição HTTP. O curl funciona de qualquer terminal. Python funciona se você preferir escrever código. Você também pode usar um cliente de API como o Apidog se quiser uma interface para tudo. Mostraremos todas as três opções.

Nenhuma configuração de faturamento é necessária antecipadamente. A camada gratuita funciona através do AI Studio e tem limite de taxa, então você pode testar sem ter um cartão registrado. Mais sobre esses limites abaixo.

Obtenha uma chave de API Gemini

Vá para Google AI Studio e faça login com sua conta Google. Clique em “Obter chave de API” e depois em “Criar chave de API”. Copie a string que ele lhe entrega e guarde-a em um local seguro. Trate-a como uma senha: qualquer pessoa que tiver a chave pode fazer gastos em sua conta.

Não cole a chave em código do lado do cliente, nem a envie para um repositório. Em vez disso, defina-a como uma variável de ambiente:

export GEMINI_API_KEY="sua_chave_aqui"

O SDK oficial do Python lê essa variável por conta própria, o que mantém o segredo fora de seus arquivos de origem. Para as etapas de configuração canônicas, consulte a documentação da API Gemini do Google.

Faça sua primeira chamada de API

O endpoint REST é um POST para o método generateContent do modelo. Aqui está em curl:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.6-flash:generateContent" \
  -H "x-goog-api-key: SUA_CHAVE_API" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {"text": "Explique como as APIs funcionam"}
        ]
      }
    ]
  }'

A chave vai no cabeçalho x-goog-api-key. O corpo é um array contents; cada entrada tem um array parts; cada parte aqui é uma string text. Esse aninhamento parece complicado para um único prompt, mas é a mesma forma que depois permite misturar texto com imagens e arquivos em uma única requisição.

Prefere Python? Instale o SDK com pip install google-genai, então:

from google import genai

client = genai.Client()  # lê GEMINI_API_KEY do ambiente
resp = client.models.generate_content(
    model="gemini-3.6-flash",
    contents="Explique como as APIs funcionam",
)
print(resp.text)

O cliente coleta GEMINI_API_KEY sozinho, então não há chave em seu código. resp.text contém a resposta gerada. Essa é uma chamada funcional em cinco linhas.

Nos bastidores, a API retorna JSON. O texto gerado está em candidates[0].content.parts[0].text. Vale a pena notar agora, porque esse é o campo exato que você afirmará quando transformar essa chamada em um teste mais adiante no guia.

Parâmetros chave que vale a pena conhecer

A requisição básica funciona, mas algumas configurações mudam o que você recebe.

• Instrução do sistema. Defina uma persona ou um conjunto de regras que se aplicam a toda a conversa, mantidas separadas do prompt do usuário. Use-o para "Responda apenas em JSON" ou "Você é um revisor de código conciso". Ele direciona o tom e o formato de forma muito mais confiável do que colocar instruções em cada mensagem.
• Tokens máximos de saída. Limite o comprimento da resposta. O 3.6 Flash pode produzir até 64 mil tokens de saída, então aumente o limite para gerações longas e diminua quando quiser controlar custos e latência.
• Entradas multimodais. O modelo lê texto, imagens, vídeo, áudio e PDFs na mesma chamada. Você os adiciona como entradas extras no array parts junto com seu texto. A saída é apenas texto, então pense nisso como muitos tipos de entrada, e palavras de saída. A janela de contexto comporta até 1M de tokens de entrada, o que é espaço para um PDF longo ou uma transcrição completa de vídeo.
• Pensamento e raciocínio. O 3.6 Flash raciocina antes de responder a prompts difíceis. Isso é o que melhora o trabalho em várias etapas, e é a razão pela qual o preço de saída inclui tokens de pensamento (mais sobre isso na próxima seção). Você pode ajustar o esforço de raciocínio quando quiser trocar profundidade por velocidade.

A lista completa de parâmetros está na documentação da API Gemini. Não adivinhe nomes de campos; a documentação é a fonte da verdade e é atualizada junto com a API.

Preços e a camada gratuita

O Gemini 3.6 Flash custa $1.50 por 1M de tokens de entrada e $7.50 por 1M de tokens de saída. Essa taxa de saída é um corte dos $9.00 cobrados pelo 3.5 Flash, e o 3.6 Flash também tende a gerar cerca de 17% menos tokens de saída para a mesma tarefa, então as economias se somam. Um detalhe a internalizar: o preço de saída inclui tokens de pensamento. O raciocínio interno do modelo é cobrado pela taxa de saída, então um prompt que aciona um raciocínio intenso pode custar mais do que o comprimento visível da resposta sugere. Orce para isso. Detalhamos a matemática completa em nosso guia de preços do Gemini 3.6 Flash.

A camada gratuita funciona através do AI Studio e é real, mas tem limite de taxa: requisições limitadas por minuto e por dia, e o Google pode usar dados da camada gratuita para melhorar seus produtos. É feita para prototipagem, não para tráfego de produção. Para aprendizado e teste, é suficiente. Para ver o quão longe ela vai, leia como usar o Gemini 3.6 Flash gratuitamente. Quando você superar essa camada, você habilita o faturamento e a mesma chave continua funcionando, sem necessidade de alterações no código.

Teste e depure a API Gemini no Apidog

O curl prova que a chamada funciona uma vez. Ele não informará quando o Google alterar um campo de resposta, quando sua chave expirar ou quando uma implantação quebrar silenciosamente a requisição. Para isso, você precisa de um teste salvo e repetível. É aqui que o Apidog ganha seu lugar no fluxo de trabalho.

Apidog é um cliente de API e plataforma de teste. Aqui está o fluxo para a chamada Gemini, do início ao fim:

1. Crie a requisição. Adicione uma nova requisição POST com a URL https://generativelanguage.googleapis.com/v1beta/models/gemini-3.6-flash:generateContent. Cole o corpo JSON de antes no corpo da requisição.
2. Armazene a chave em uma variável de ambiente. Adicione uma variável chamada GEMINI_API_KEY a um ambiente Apidog e, em seguida, faça referência a ela no cabeçalho x-goog-api-key como {{GEMINI_API_KEY}}. O segredo permanece fora da requisição compartilhada, e você pode trocar chaves por ambiente (dev, staging, prod) sem tocar na chamada em si.
3. Adicione asserções. Após a execução da requisição, afirme na resposta JSON: o status é 200, e candidates[0].content.parts[0].text existe e não está vazio. Agora, uma execução bem-sucedida significa que a API realmente respondeu, não apenas que retornou algo.
4. Salve e agende. Mantenha a requisição em uma coleção e agende-a como um teste de regressão. Execute-a em um temporizador ou dentro do CI, e você descobrirá o momento em que a chamada Gemini parar de se comportar, antes que seus usuários o façam.

Baixe o Apidog e você pode ter este teste funcionando em poucos minutos. Esse é o encaixe honesto aqui: o Apidog não executa o modelo, ele garante que a API da qual você depende continue respondendo da maneira que seu aplicativo espera.

Erros comuns e soluções

Três falhas cobrem a maioria do que você encontrará no início.

• 401 Não Autorizado (chave inválida). A chave está errada, revogada ou faltando no cabeçalho. Verifique se x-goog-api-key contém a string exata do AI Studio e se sua variável de ambiente realmente foi resolvida. Um espaço em branco ou um {{GEMINI_API_KEY}} não expandido são os culpados usuais.
• 429 Muitas Requisições (limite de taxa). Você atingiu o limite por minuto ou por dia da camada gratuita. Diminua a taxa de requisições, adicione uma nova tentativa com backoff ou habilite o faturamento para aumentar o limite. Ciclos de teste apertados acionam isso rapidamente.
• 404 Não Encontrado (modelo não encontrado). Isso é quase sempre um erro de digitação no ID do modelo. É gemini-3.6-flash, exatamente. Não gemini-3.5-flash, não gemini-flash-3.6. A camada Lite neste mesmo lançamento é gemini-3.5-flash-lite, um modelo diferente na linha 3.5, então não confunda os fios entre eles.

FAQ

Qual é o ID exato do modelo para o Gemini 3.6 Flash? É gemini-3.6-flash. Use-o como o nome do modelo no SDK e no caminho da URL REST logo antes de :generateContent.

A API Gemini 3.6 Flash é gratuita para usar? Existe uma camada gratuita através do AI Studio, e ela tem limite de taxa. É ótima para prototipagem e aprendizado. O tráfego de produção exige que o faturamento esteja habilitado. Para detalhes, veja como usá-la gratuitamente.

O que posso enviar para o modelo? Texto, imagens, vídeo, áudio e PDF, até uma janela de contexto de 1M de tokens. A saída é apenas texto.

Por que minha conta veio mais alta do que as respostas visíveis? O preço de saída de $7.50 por 1M de tokens inclui os tokens de pensamento do modelo. Prompts com raciocínio intenso são cobrados por mais do que o comprimento da resposta mostra na tela.

É o mesmo que a API Gemini 3.5 Flash mais antiga? A forma da chamada é a mesma, então se você usou a API Gemini 3.5, você troca o ID do modelo e pronto. O 3.6 Flash reduz o preço de saída e usa menos tokens de saída para o mesmo trabalho.

Posso usar a mesma chave em curl, Python e Apidog? Sim. Uma chave do AI Studio funciona em todos eles. Mantenha-a em uma variável de ambiente em cada ferramenta, em vez de codificá-la diretamente, e você pode girá-la ou revogá-la em um só lugar.

Para onde ir a partir daqui

Você tem uma chave, uma chamada funcionando em curl e Python, os parâmetros importantes e um teste de regressão salvo monitorando o endpoint. Comece na camada gratuita, mantenha sua chave em uma variável de ambiente e conte com a documentação oficial para qualquer coisa além do básico. Quando a chamada se tornar algo do qual seu aplicativo depende, envolva-a em um teste Apidog para que uma alteração silenciosa da API nunca chegue aos seus usuários primeiro.