O caminho mais curto para integrar a Gemini API é: abrir o AI Studio com uma conta Google, criar uma API Key, instalar o SDK e enviar a primeira requisição generateContent. Com tudo em ordem, o processo leva menos de vinte minutos. O que realmente costuma travar não é "conseguir chamar", mas escolher a entrada errada, escrever o ID do modelo incorretamente, confundir a cota gratuita com o plano pago e colocar a Key onde ela não deveria estar.

Este artigo segue a ordem real de integração: primeiro separa AI Studio e Vertex AI; depois cria a Key, instala o SDK e envia requisições com curl e Python; em seguida trata nomenclatura de modelos, instruções de sistema, streaming e configurações de segurança; por fim, lista as causas comuns de 400, 403 e 429 e um checklist de segurança da Key.

Nota: Google e Gemini são marcas da Google LLC. Nomes de modelos, cotas gratuitas e regras de cobrança podem mudar. Este artigo usa como exemplo o fluxo comum em outubro de 2026; siga a documentação oficial do Google e a página de preços do site.

1. Separe primeiro AI Studio e Vertex AI

A Gemini API tem duas entradas usuais, com sistemas de conta e administração diferentes. Escolher errado gera retrabalho de permissões ou faturamento.

Item Google AI Studio Vertex AI
Entrada Console no navegador, voltado a testes rápidos de desenvolvedores Console do Google Cloud, voltado a uso por projeto
Requisitos de conta Basta uma conta Google para começar Projeto Cloud, conta de faturamento e permissões IAM
Credenciais API Key gerada no AI Studio Service account ou Key controlada, com IAM
Cobrança Plano gratuito e plano pago coexistem Cobrança por projeto Cloud
Região e dados Sujeitos aos termos do AI Studio Região selecionável, sujeita aos termos do Cloud e à configuração do projeto
Cenário indicado Protótipos, aprendizado, validação em pequena escala Sistemas de produção, auditoria e equipes com requisitos de permissão

Desenvolvedores individuais e equipes pequenas normalmente usam o AI Studio para validar o fluxo; quando entram contratos, região de dados e auditoria unificada, avaliam o Vertex AI. Não misture Keys, cotas e faturas dos dois, e não use uma Key do AI Studio para chamar endpoints do Vertex AI.

2. Criar a primeira API Key

  1. Entre no Google AI Studio com uma conta Google.
  2. Acesse a página de gerenciamento de API Keys e escolha criar uma API Key.
  3. Selecione um projeto do Google Cloud; se não houver, crie um conforme as instruções da página.
  4. Copie a Key gerada e guarde-a imediatamente em variável de ambiente do servidor ou em um gerenciador de senhas.
  5. Envie uma mensagem de teste no Playground para confirmar que a Key e o modelo funcionam.
  6. Dê à Key um nome que indique a finalidade, para facilitar rotação e revogação futuras.

O AI Studio oferece um plano gratuito para testes; modelos disponíveis, taxa de requisições e cota variam conforme a conta e o período. Ao habilitar o faturamento no projeto Cloud associado, é possível entrar no plano pago. Não trate números de cota de artigos antigos como compromisso atual: valem o que o console mostra e a documentação oficial.

Depois de criar a Key, confirme a qual projeto Cloud ela pertence. A cota costuma ser calculada por projeto, e misturar teste e produção faz com que outra pessoa esgote a cota. Se precisar de mais cota, habilite o faturamento no projeto Cloud, configure alertas de orçamento e observe o uso real por uma semana.

3. Instalar o SDK e enviar a primeira requisição

Para Python, recomenda-se a versão 3.10 ou superior, com o SDK oficial instalado em um ambiente virtual.

python3 -m venv .venv
source .venv/bin/activate
pip install -U google-genai
export GEMINI_API_KEY="sua-chave"

Comece com curl para eliminar o fator SDK. Use um marcador no lugar do ID do modelo; o nome real vem da lista de modelos ou da página de preços do site.

curl "https://generativelanguage.googleapis.com/v1beta/models/<ID-DO-MODELO>:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Explique em uma frase o que é um gateway de API"}]}
    ],
    "generationConfig": {"maxOutputTokens": 256, "temperature": 0.7}
  }'

Depois que o curl retornar 200, passe para o SDK de Python:

import os
from google import genai

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

resp = client.models.generate_content(
    model="<ID-DO-MODELO>",
    contents="Explique em uma frase o que é um gateway de API",
)
print(resp.text)

O campo model deve conter o ID completo do modelo, não apenas o nome da família. Modelos diferentes aceitam tipos de entrada e parâmetros diferentes; um erro aparece como 400 ou 404.

4. Nomenclatura de modelos, instruções de sistema e parâmetros

Os IDs do Gemini costumam combinar família e versão. O mais seguro é consultar primeiro a lista de modelos disponíveis para a conta:

curl "https://generativelanguage.googleapis.com/v1beta/models" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

Não adivinhe modelos que não aparecem na lista. Na escolha, divida por tarefa: tarefas leves em faixas de baixa latência; raciocínio complexo e documentos longos em faixas superiores. Faixas e preços seguem a página de preços.

Os IDs mudam com as versões, e IDs antigos podem ser marcados como obsoletos ou removidos. Coloque o nome do modelo em um arquivo de configuração, não espalhado pelo código; na atualização, altere um único ponto e use amostras de regressão para confirmar que a saída não mudou de forma relevante.

Instruções de sistema fixam papel e regras de saída e são úteis em tradução, extração e atendimento:

resp = client.models.generate_content(
    model="<ID-DO-MODELO>",
    contents="Traduza esta frase para o inglês: integração concluída",
    config={"system_instruction": "Você é um tradutor de documentação técnica e deve produzir apenas a tradução."},
)

Os parâmetros de geração mais usados são temperature, maxOutputTokens e topP. Quando precisar de resultados estruturados, peça JSON ao modelo e faça a análise e a validação no código; não presuma que o modelo sempre obedecerá ao formato, e prepare desde o início lógica de repetição e fallback.

5. Streaming e configurações de segurança

Streaming é adequado a interfaces de chat e respostas longas. Na API REST, acrescente :streamGenerateContent ao método e inclua alt=sse; no SDK de Python, use generate_content_stream:

for chunk in client.models.generate_content_stream(
    model="<ID-DO-MODELO>",
    contents="Explique em três pontos o que é limitação de taxa",
):
    print(chunk.text, end="")

As configurações de segurança permitem ajustar limites de bloqueio por categoria; as categorias comuns incluem assédio, ódio, conteúdo sexual e conteúdo perigoso. O limite padrão atende à maioria dos negócios; reduzi-lo amplia o escopo de conteúdo e exige avaliação da política do produto e da legislação local. Não desative as configurações de segurança por completo apenas para "passar no teste", sobretudo em produtos voltados ao público.

6. Como diagnosticar 400, 403 e 429

Código Causa comum Direção do tratamento
400 Estrutura JSON inválida, parâmetro não suportado, ID de modelo incompatível com a interface Confira campo por campo o corpo da requisição e comece pela requisição mínima
403 Key inválida ou restrita, API não habilitada, restrição de projeto ou região Teste outra Key e verifique permissões do projeto e status da conta
404 ID do modelo errado, versão ou caminho da interface incorreto Consulte a lista de modelos e confirme v1beta e o nome do método
429 Cota gratuita esgotada, excesso de requisições por minuto, concorrência alta Repita com recuo exponencial, reduza a concorrência e avalie o plano pago
500/503 Falha temporária do servidor Repita um número limitado de vezes; se persistir, faça degradação ou troque de rota

Não reenvie um 429 imediatamente. O correto é aplicar recuo com jitter aleatório, definir um número máximo de tentativas e registrar as falhas nos logs. O plano gratuito costuma ter limites de taxa mais rígidos; testes de carga e tarefas em lote devem ser planejados separadamente.

7. Checklist de segurança da Key

  • Mantenha a Key apenas em variáveis de ambiente do servidor ou em um serviço de gestão de segredos; não a coloque no front-end, no repositório nem em conversas.
  • Use uma Key para cada ambiente — produção, teste e desenvolvimento — isolando cotas e permissões.
  • Faça rotação periódica e revogue imediatamente quando alguém sair ou o projeto terminar.
  • No console da nuvem, restrinja as APIs que a Key pode chamar para reduzir o impacto de um vazamento.
  • Ative alertas de uso e, ao detectar chamadas anômalas, desative a Key antes de investigar.
  • Não exponha a Key completa em capturas de tela, gravações ou tickets.

8. Integrar o Gemini por uma entrada compatível com OpenAI

Se a equipe já tem o SDK da OpenAI e um conjunto de código de chamadas, pode usar a entrada compatível com OpenAI do ZSQH AI Gateway, cuja Base URL é https://ai.zhongshangqihang.com/v1. Basta alterar base_url, api_key e model:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZSQH_API_KEY"],
    base_url="https://ai.zhongshangqihang.com/v1",
)

resp = client.chat.completions.create(
    model="<nome do modelo Gemini na página de preços>",
    messages=[{"role": "user", "content": "Responda apenas OK"}],
)
print(resp.choices[0].message.content)

Essa abordagem é indicada a equipes que precisam de fatura unificada para vários modelos, pagamento em yuan e ambiente de rede local. Os parâmetros nativos do Gemini e os campos multimodais não têm compatibilidade total assegurada; valide item por item com requisições reais antes de migrar. O cadastro está aqui, e modelos e preços seguem a página de preços.

Perguntas frequentes

A Gemini API tem cota gratuita?

O AI Studio oferece um plano gratuito, mas modelos disponíveis, taxa e cota mudam, e os termos de dados podem diferir do plano pago. Para validar protótipos, o plano gratuito serve; para operação formal, reavalie cotas e custos com base no plano pago.

O que fazer se a API Key vazar?

Primeiro revogue ou troque a Key no console, depois consulte os logs de uso para delimitar as chamadas anômalas e, por fim, investigue o canal de vazamento. Apagar a Key do código não basta: credenciais já expostas devem ser tratadas como inválidas.

A rede local consegue chamar a Gemini API diretamente?

A qualidade do link varia por região e operadora, e podem ocorrer timeouts ou falhas de conexão. A prática comum é colocar as requisições em servidores com acesso estável ou usar um gateway com interface compatível com OpenAI; os limites exatos dependem do link real e da documentação oficial.

Por que o curl funciona e o SDK de Python dá erro?

Verifique primeiro se o SDK e as dependências estão atualizados; depois confirme a grafia de model, a configuração de proxy e as variáveis de ambiente. Quando o SDK retorna 404, concentre-se no ID do modelo e no caminho da interface, sem alterar várias variáveis ao mesmo tempo.

É possível chamar a Gemini API diretamente com o SDK da OpenAI?

O Google oferece uma entrada compatível com OpenAI, e gateways locais também costumam fornecer uma camada de compatibilidade, mas o escopo de parâmetros varia. Valide multimodalidade, chamadas de ferramentas e saída estruturada com requisições reais; não presuma equivalência total.

Próximo passo

Siga o fluxo deste artigo até a requisição mínima funcionar e depois conecte logs de negócio, repetição e monitoramento de uso. Para administrar em um único painel o consumo de Gemini e de outros modelos, a fatura em yuan e as permissões de Key, comece pelo cadastro no ZSQH AI Gateway; os preços estão na página de preços.

Leituras relacionadas: