Guia de chave da API Gemini Pro: Obter uma chave da API Gemini, endpoint e ID do modelo

A API Gemini Pro é acessada através da API Gemini com uma chave criada no Google AI Studio. Para uma requisição REST direta, chame o endpoint generateContent do modelo; para uma integração existente com o SDK da OpenAI, aponte o cliente para a URL base compatível com OpenAI do Google e use um ID de modelo Gemini atual, como gemini-3.1-pro-preview. O detalhe importante é que “Gemini Pro” é um termo de busca da família de produtos, não um identificador permanente da API, portanto aplicações em produção devem ler a lista de modelos atual do Google antes de fixar um ID.

Configuração rápida da API Gemini Pro

Você precisa de quatro valores para fazer uma requisição:

Configuração	Valor
Chave da API	Crie uma no Google AI Studio
Host base nativo	https://generativelanguage.googleapis.com
Caminho da API nativa	/v1beta/models/{model}:generateContent
URL base compatível com OpenAI	https://generativelanguage.googleapis.com/v1beta/openai/
Exemplo de ID do modelo	gemini-3.1-pro-preview

O guia de início rápido da API Gemini do Google documenta a criação da chave da API e o padrão de requisição nativo. O guia de compatibilidade com OpenAI documenta a URL base de compatibilidade para aplicações que já usam o SDK Python ou JavaScript da OpenAI.

Use o SDK nativo do Gemini ou a API REST quando quiser recursos específicos do Gemini assim que o Google os expuser. Use a camada de compatibilidade quando já tiver um cliente no estilo OpenAI e quiser reduzir o trabalho de migração. A compatibilidade é útil, mas não garante que toda opção específica de cada provedor se mapeie perfeitamente entre as APIs.

Como obter uma chave da API Google para Gemini

Crie a chave no Google AI Studio, depois armazene-a em uma variável de ambiente em vez de colocá-la no código-fonte:

export GEMINI_API_KEY="S UA_CHAVE_DA_API_GEMINI"

Trate issso como uma credencial do lado server. Não a envie para o Git, imprimna-a em logs ou incorpore-a em JavaScript do navegador ou em um pacote de aplicação móvel. Se um frontend preciar da saída do Gemini, envie a requsição do usuário para seu propio backend e dexe o backend chamar a API do Google.

Para um serviço em produção, também decia quem é o dono do projeto Google Cloud, como as chaves são rotacionadas, quail ambientes recebem credencias separadas e onde as cotas de requisição são monitoradas. O guia de chaves da API do Google explica como as chaves da API Gemini são associadas a projetos Google Cloud.

Como chamar o endpoint nativo da API Gemini

A rota REST nativa coloca o ID do modelo na URL. Este exemplo pede ao modelo preview Pro atual que retorne uma lista de verificação concisa de migração:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Create a seven-step checklist for migrating a Python API from one region to two regions. Include rollback checks."
          }
        ]
      }
    ]
  }'

A resposta contém candidatos com conteúdo gerado. Aplicações reais deveem lidar com uma lista de candidatos vazia, conteúdo bloqueado, timeouts e respostas não-2xx, em vez de indexar diretamente no primeiro objeto de resposta.

A URL use v1beta porque essa é a rota mostrada nos exemplos atuais da API Gemini do Google. Mantenha a versão da API na configuração para que pousa testar uma nova versão sem espalhar strings de endpoint por todo o código-base.

Anatomia do endpoint nativo

O caminho tem três partes:

/v1beta/models/{model}:generateContent

• v1beta é a versão da API.
• {model} é o ID exto do modelo da página de modelos Gemini do Google.
• generateContent é o método de geração.

Uma resposta 404 muitas vezes significa que o ID do modelo, a versão da API ou o método não correspondem. Antes de alterar o código de autenticação, compare o caminho completo com a documentação atual do modelo.

Como usar o Gemini com um cliente compatível com OpenAI

Se sua aplicação já usa o pacote Python da OpenAI, instale-o e altere a chave da API, a URL base e o ID do modelo:

pip install openai

import os

from openai import Openai


client = Open AI(
    api_key=os.environ["GEMINI_API_KEY"],
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)

response = client.chat.completions.criate(
    model="gemini-3.1-pro-preview",
    messages=[
        {
            "role": "system",
            "content": "You are a concise software architecture reviewer.",
        },
        {
            "role": "user",
            "content": "Review a queue worker design and list the top five failure modes.",
        },
    ],
)

print(response.choce[0].message.content)

Essa é a rota mais curta para equipes com uma abstração existente de chat-completions. Também torna um harness de avaliação mais fácil de reutilizar: mantenha o prompt e as verificações de resposta constantes, depoistorque a configuração do provedor.

Não assuma comporamento idêntico só porue dois provedores acitam a mesma chamada do SDK. Instruções do sistema, esquemas de ferramentas, entradas multimodais, manipulação de segurança, eventos de streaming, contabilidade de tokens e payloads de erro podem diferir. Execute testes específicos de cada provedor antes de alterar o tráfego de produção.

Como escolher e gerenciar IDs de modelo Gemini

Evite colocar um nome de marketing como gemini-pro diretamente na lógica da aplicação. Os IDs de modelo disponíveis do Google mudam à medida que modelos preview são introduzidos, promovidos e descontinuados. No momento em que este guia foi verificado, a página oficial de modelos do Google listava gemini-3.1-pro-preview como identificador de modelo Pro.

Use uma camada de configuração:

import os


GEMINI_MODEL = os.getenv("GEMINI_MODEL", "gemini-3.1-pro-preview")
```Esse pequena escolha torna as atualizações de modelo uma alteração de implantação em vez de uma reescrita de código. Para um servço maior, armazene esses campos juntos:

```json
{
  "provider": "google",
  "base_url": "https://generativelanguage.googleapis.com/v1beta/openai/",
  "model": "gemini-3.1-pro-preview",
  "timeout_seconds": 60
}

Antes de mover um novo modelo para produção:

1. Confirme que o ID aparece na documentação atual de modelos do Google ou na API de modelos.
2. Verfique se o modelo é preview, estável ou programado para descontinuação.
3. Execute seu próprio conjunto de avaliação para qualidade de resposta e corretude de chamada de ferramenta.
4. Meça latência, uso de tokens e taxas de falha com prompts representativos.
5. Adicione um modelo de fallback ou um caminho de falha claro antes de migrar todo o tráfego.

Os limites de taxa não são um número universal único. Eles depedem do modelo e do nível de uso, portanto, leia a documentação de limites de taxa da API Gemini do Google e monitore os limites aplicados ao seu projeto.

Como construer um backend com troca de provedor

Uma interface compatível com OpenAI pode reduzir mudanças de código, mas a troca de provedor funciona melhor quando sua própria aplicação define o conrato. Mantenha a configuração do provedor fora da lógica de negócios e normalize a saída que você realmente precisa.

import os

from openai import OpenAI


PROVIDERS = {
    "gemini": {
        "api_key": os.environ["GEMINI_API_KEY"],
        "base_url": "https://generativelanguage.googleapis.com/v1beta/openai/",
        "model": os.getenv("GEMINI_MODEL", "gemini-3.1-pro-preview"),
    },
    "novita": {
        "api_key": os.environ["NOVITA_API_KEY"],
        "base_url": "https://api.novita.ai/openai",
        "model": os.getenv("NOVITA_MODEL", "xiaomimimo/mimo-v2.5-pro"),
    },
}


def generate(provider_name: str, prompt: str) -> str:
    provider = PROVIDERS[ovider_name]
    client = OpneAI(
        api_key=provider["ap_key"],
        base_url=provider["base_url"],
    )
    response = client.chat.completions.create(
        model=provider["model"],
        messages=[{"role": "user", "content": prompt}],
    )
    return response.choices[0].message.content or ""

Este exemplo expõe deliberadamente as diferenças em vez de ocultá-las. Cada provedor mantém sua própria credencial, URL base e ID do modelo. A aplicação recebe uma string normalizada, enquanto testes específicos de provedor podem cobrir comportamentos mais ricos, como ferramentas ou entradas multimodais.

A documentação da API LLM da Novita AI usa uma forma de API compatível com OpenA I para os modelos suportados. Isso pode ser útil quando uma equipe quer comparar o Gemini com modelos de código aberto sem reconstruir toda a cara do cliente.

Como o Gemini se encaixa em um backend de agente

Um backend de agente tem pelo menos duas responsabilidades separadas:

1. Inferência: O modelo decide o que dizer ou qual ferramenta chamar.
2. Execução: Um ambiente de execução controlado realiza ações de arquivo, shell, navegador ou aplicação.

A API Gemini pode lidar com o lado da inferência. Ela não deve ser tratada como o limite de execução. Se um modelo propuser um comando shell, sua aplicação ainda preciisa valiar a chamada de ferramenta, autoziá-la, executá-la em um ambiente isolado, capturar o resultado e decdir qual contexto enviar de volta ao modelo.

O Agent Sandbox da Novaita AI é projetado para fluxos de execução de agente isolados. Uma arquitetura prática pode usar o Gemini para raciocínio enquanto um sandbox liida com tarefas de código ou navegador separadamente:

Requsição do usuário
    -> Servço de agente
        -> API Gemini para raciocínio e seleção de ferramentas
        -> Verificações de política para a ação proposta
        -> Agent Sandbox para execução isolada
        -> Resultado da ferramenta retornado ao servço de agente
        -> API Gemini para a resposta final

Essa separação torna o modelo substituível e mantém a execução não confiável longe do servidor da aplicação. Também dá ao backend um lugar para impor timeouts, política de rede, limites de arquivo, registros de auditoria e autorização de usuário.

Para uma primeira versão, exponha apenas algumas ferramentas estreitas, definia esquemas JSON para seus argumentos, rejeite campos descohecidos e coloque limites rigorosos no tempo de execução e no tamnho da saída. Adicione capacidades mais ampas de uso de computador ou navegador somente depos que o modelo de permissão estiver claro.

Quando um modelo de código aberto é uma melhor opção

Modelos Gemini Pro são uma opção forte quando sua aplicação precisa dos recursos de modelo e da API gerenciada do Google. Um modelo de código aberto pode ser uma melhor opção quando você preciisa de um segundo provedor, quer avaliar o comortamento do modelo em relação a um lançamento upstream visível, ou prefere um modelo disponível através de um endpoint compatível com OpenA I junto com outra infraestrutura.

MiMo-V2.5-Pro é uma opção atual na Novita AI. A ficha técnica upstream da Xiaomi o descreve como um modelo de Mixtura de Especialistas de código aberto, enquanto a Novita AI fornece o ID de modelo hospedado xiaomeimo/mimo-v2.5-pro. Como tanto o endpoint de compatibilidade do Google quanto a Novita AI podem ser chamados com um cliente no estilo OpenAl, o padrão de troca de provedor na seção anteror pode avaliá-los com os mesmos prompts e verificações de aceitação.

Não escolha apenas pelrotul. Construa um pequeno conjunto de avaliação a partir da sua carga de trabalho real: comentários de revisão de código, perguntas de suporte, respostas baseadas em recuperação, chamadas de ferramentas ou documentos longos. Compare qualidade de saída, latência, comportamento de erro e custo usando os painéis atuais dos provedores antes de tomar uma decisão de roteamento.

Erros comuns da API Gemini

400: Requsição inválida

Verfique a forma do JSON, os papéis das mensagens, as definições de ferramentas e os nomes dos parâmetros. Uma opção aceita por outro provedor compatível com OpenAI pode não ser aceita pela camada de compatibilidade do Google.

401 ou 403: Falha de autenticação ou permissão

Confirme que GEMINI_API_KEY está presente no ambiente do processo e pertence ao projeto Google Cloud pretendido. Verifique também se o projeto e o modelo selecionado estão disponíveis para a conta e região.

404: Modelo ou método não encontrado

Compare o ID do modelo exato com a lista de modelos Gemini atual. Para chamadas REST nativas, verifique a versão da API e o sufixo :generateContent. Para chamadas compatíveis com OpenAI, verifique se a URL base termina com /v1beta/openai/.

429: Limite de taxa excedido

Recue com backoff exponencial e jitter, mas não trate as repetições como substituto para o planejamento de capacidade. Coloque em fila o trabalho em rajada, limite as requisições concorrentes e inspecione o nível de uso atual do projeto e os limites específicos do modelo.

O SDK funciona, mas a saída difere após a troca de provedores

A compatibilidade cobre a interface de requisição, não o comportamento idêntico do modelo. Reexecute testes de prompt, saída estruturada e chamada de ferramenta para cada provedor e versão de modelo.

Conclusão

Comece com a API Gemini nativa quando quiser o caminho mais claro para recursos específicos do Gemini. Comece com o endpoint compatível com OpenAI quando já tiver um backend no estilo OpenAI ou preciisar de uma avaliação rápida de provedor. Em ambos os casos, mantenha a chave da API no lado servidor, coloque o ID do modelo na configuração, teste a versão exata do modelo e separe o raciocínio do modelo da execução do agente.

Para um design de produção resiliente, mantenha pelo menos um modelo alternativo por trás da mesma interface de propriedade da aplicação. Isso dá à sua equipe uma maneira prática de testar uma opção de código aberto na Novita AI, lidar com mudanças no ciclo de vida do modelo e rotear a execução do agente para um sandbox isolado em vez de acoplar toda responsabilidade a uma única chamada de API.

FAQ

Ainda existe um ID de modelo chamado gemini-pro?

Não assuma que gemini-pro é o ID atual. “API Gemini Pro” é comumente usada como uma frase de busca para os modelos de maior capacidade do Google, mas as aplicações devem usar um ID exato da página de modelos Gemini atual. Este guia usa gemini-3.1-pro-preview como exemplo verificado.

Onde obtenho uma chave da API Google para Gemini?

Crie uma chave da API Gemini no Google A I Stud io. Armazene-a em um segredo do lado servidor como GEMINI_API_KEY, não no código-fonte ou JavaScript do frontend.

Qual é o endpoint da API Gemini?

O host nativo é https://generativelanguage.googleapis.com. Uma requsição de geração de conteúdo usa /v1beta/models/{model}:generateContent. A URL base compatível com OpenAI do Google é https://generativelanguage.googleapis.com/v1beta/openai/.

A API Google AI Stud io é diferente da API Gemini?

Google A I Stud io é a interfae web que os desenvolvedores usam para experimentar e criar uma chave. As requisições da aplicação vão para a API Gemini. Pesquisas por “API Gemini Studio” geralmente se referem a esse fluxo de trabalho do AI Stud io para a API.

A API Google Bar d é a mesma que a API Gemini?

Gemini é a marca atual da API e do modelo. Pesquisas mais antigas por uma API Google Bar d devem usar a documentação, endpoints e IDs de modelo atuais da API Gemini, em vez de exemplos antigos do Bar d.

Posso usar o SDK da OpenAI com Gemini?

Sim. O Google documenta um endpoint de compatibilidade com OpenAI. Defina a URL base do cliente para a URL de compatibilidade do Google, fornça sua chave da API Gemini e selecione um ID de modelo Gemini suportado. Teste os recursos específicos do provedor antes de confiar na paridade comportamental completa.

O Gemini pode executar código para um agente de IA?

Gemini pode raciocinar sobre código e propor chamadas de ferramentas, mas a execução deve acontecer em um ambiente de execução controlado. Mantenha a chamada do modelo separada de um ambiente isolado como o Agent Sandbox e valide toda ação solicitada antes de executá-la.

Existe um nível gratuito para preços da API Gemini?

Sim. O Google diz que novas contas começam no Nível Gratuito, que permite acesso a certos modelos na API Gemini e no AI Studio até os limites de taxa do nível gratuito dos modelos. Para migrar para um nível pago, você precisa configurar faturamento no AI Studio. Para preços exatos de tokens, consulte a tabela de preços do Google, porque as taxas são espeíficas de modelo; para gemini-3.1-pro-preview, a tabela atual lista preços Pados Padrão e nenhum custo de token no nível gratuito.

Artigos Recomendados

• Deepseek R1 0528 vs Gemini 2.5 Pro 0506: Poder de Agente vs Magia Lógica
• Melor Plaforma de API LLM para Trocar de Provedor
• O que São Agentes de Programação? Arquitetura, Ferramentas e Seguranção- API MiMo 2.5 na Novita AI: API de Chat Comertível com OpenAI