Guia da API Gemini Pro: Chave, Endpoint, IDs de Modelo e Compatibilidade com OpenAI

A API Gemini Pro é acessada através da Gemini API 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 para uma família de produtos, não um identificador de API permanente, portanto, aplicações em produção devem ler a lista atual de modelos 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 de 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 de modelo	gemini-3.1-pro-preview

O início rápido da Gemini API do Google documenta a criação da chave de API e o padrão de requisição nativa. 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 da Gemini ou a API REST quando quiser recursos específicos da 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 todas as opções específicas de cada provedor sejam mapeadas perfeitamente entre as APIs.

Como obter uma chave de API do Google para Gemini

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

export GEMINI_API_KEY="SUA_GEMINI_API_KEY"

Trate isso como uma credencial do lado do servidor. Não a commite no Git, imprima em logs ou incorpore em JavaScript do navegador ou em um pacote de aplicativo móvel. Se um frontend precisar da saída do Gemini, envie a requisição do usuário para seu próprio backend e deixe o backend chamar a API do Google.

Para um serviço de produção, decida também quem é o proprietário do projeto Google Cloud, como as chaves são rotacionadas, quais ambientes recebem credenciais separadas e onde as cotas de requisição são monitoradas. A orientação sobre chaves de API do Google explica como as chaves da API Gemini são associadas a projetos do 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 Pro preview atual que retorne uma lista de verificação de migração concisa:

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": "Crie uma lista de verificação de sete etapas para migrar uma API Python de uma região para duas regiões. Inclua verificações de reversão."
          }
        ]
      }
    ]
  }'

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

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

Anatomia do endpoint nativo

O caminho tem três partes:

/v1beta/models/{model}:generateContent

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

Uma resposta 404 geralmente 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 de API, a URL base e o ID do modelo:

pip install openai

import os

from openai import OpenAI


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

response = client.chat.completions.create(
    model="gemini-3.1-pro-preview",
    messages=[
        {
            "role": "system",
            "content": "Você é um revisor de arquitetura de software conciso.",
        },
        {
            "role": "user",
            "content": "Revise o design de um worker de fila e liste os cinco principais modos de falha.",
        },
    ],
)

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

Esta é a rota mais curta para equipes com uma abstração de chat-completions existente. Também facilita a reutilização de um harness de avaliação: mantenha as verificações de prompt e resposta constantes e troque a configuração do provedor.

Não presuma comportamento idêntico só porque dois provedores aceitam a mesma chamada de SDK. Instruções de sistema, esquemas de ferramentas, entradas multimodais, tratamento de segurança, eventos de streaming, contabilização de tokens e cargas de erro podem ser diferentes. 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 conforme 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 um identificador de modelo da classe Pro.

Use uma camada de configuração em vez disso:

import os


GEMINI_MODEL = os.getenv("GEMINI_MODEL", "gemini-3.1-pro-preview")

Essa pequena escolha faz com que as atualizações de modelo sejam uma alteração de implantação, não uma reescrita de código. Para um serviço maior, armazene esses campos juntos:

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

Antes de colocar um novo modelo em produção:

1. Confirme que o ID aparece na documentação atual do modelo do Google ou na API de modelos.
2. Verifique 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 correção de chamadas de ferramentas.
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 deslocar todo o tráfego.

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

Como construir um backend com alternância de provedor

Uma interface compatível com OpenAI pode reduzir alterações de código, mas a alternância de provedor funciona melhor quando sua própria aplicação define o contrato. 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[provider_name]
    client = OpenAI(
        api_key=provider["api_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 de modelo. A aplicação recebe uma string normalizada, enquanto testes específicos de cada 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 OpenAI para modelos suportados. Isso pode ser útil quando uma equipe deseja comparar o Gemini com modelos de código aberto sem reconstruir toda a camada de 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 runtime controlado executa ações de arquivo, shell, navegador ou aplicativo.

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 de shell, sua aplicação ainda precisa validar a chamada de ferramenta, autorizá-la, executá-la em um ambiente isolado, capturar o resultado e decidir qual contexto enviar de volta ao modelo.

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

Requisição do usuário
    -> Serviç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 serviç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 arquivos, registro de auditoria e autorização de usuário.

Para uma primeira versão, exponha apenas algumas ferramentas restritas, defina esquemas JSON para seus argumentos, rejeite campos desconhecidos e coloque limites rígidos no tempo de execução e no tamanho da saída. Adicione capacidades mais amplas de uso de computador ou navegador somente após o modelo de permissão estar claro.

Quando um modelo de código aberto é uma escolha melhor

Os modelos Gemini Pro são uma opção forte quando sua aplicação precisa das capacidades de modelo gerenciado do Google. Um modelo de código aberto pode ser uma escolha melhor quando você precisa de um segundo provedor, deseja avaliar o comportamento do modelo em relação a uma versão upstream visível ou prefere um modelo disponível através de um endpoint compatível com OpenAI junto com outra infraestrutura.

O MiMo-V2.5-Pro é uma opção atual na Novita AI. A ficha técnica do modelo upstream da Xiaomi o descreve como um modelo MoE (Mixture-of-Experts) de código aberto, enquanto a Novita AI fornece o ID de modelo hospedado xiaomimimo/mimo-v2.5-pro. Como tanto o endpoint de compatibilidade do Google quanto a Novita AI podem ser chamados com um cliente no estilo OpenAI, o padrão de alternância de provedor na seção anterior pode avaliá-los com os mesmos prompts e verificações de aceitação.

Não escolha apenas pelo rótulo. 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 a qualidade da saída, latência, comportamento de erro e custo usando os painéis atuais do provedor antes de tomar uma decisão de roteamento.

Erros comuns da API Gemini

400: Requisição inválida

Verifique a estrutura do JSON, funções das mensagens, definições de ferramentas e nomes de 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 exato do modelo com a lista atual de modelos Gemini. 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

Tente novamente com backoff exponencial e jitter, mas não trate as tentativas como substituto para o planejamento de capacidade. Coloque em fila o trabalho em rajadas, limite 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. Execute novamente os testes de prompt, saída estruturada e chamada de ferramenta para cada provedor e versão do 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 precisar de uma avaliação rápida de provedor. Em ambos os casos, mantenha a chave de API no lado do 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 todas as responsabilidades a uma única chamada de API.

FAQ

Ainda existe um ID de modelo chamado gemini-pro?

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

Onde obtenho uma chave de API do Google para Gemini?

Crie uma chave de API Gemini no Google AI Studio. Armazene-a em um segredo do lado do 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 requisiçã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 do Google AI Studio é diferente da API Gemini?

O Google AI Studio é a interface 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 “Google AI Studio API” geralmente se referem a esse fluxo de trabalho do AI Studio para a API.

A API Google Bard é a mesma que a API Gemini?

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

Posso usar o SDK da OpenAI com o Gemini?

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

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

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

Artigos Recomendados

• Melhor Plataforma de API LLM para Trocar de Provedores
• O que são Agentes de Código? Arquitetura, Ferramentas e Segurança
• API MiMo 2.5 na Novita AI: Chat API Compatível com OpenAI