Como chamar a API Gemini com o OpenAI SDK: tutorial de integração alterando apenas base_url, key e nome do modelo

O Google já foi bem direto: a Gemini API oferece suporte à compatibilidade com OpenAI, podendo ser chamada com o SDK Python da OpenAI, o SDK JavaScript e REST; no exemplo oficial, o base_url é https://generativelanguage.googleapis.com/v1beta/openai/, e o nome do modelo é gemini-3.5-flash (Google AI for Developers).
Isso é muito útil para equipes que já têm código usando o SDK da OpenAI. Você não precisa reescrever um client, nem alterar a estrutura das mensagens: primeiro troque três configurações, faça rodar e só depois decida se vale usar recursos nativos do Gemini.

Primeiro, veja quais são os três pontos a alterar

A documentação do Google deixa claro logo após o exemplo: as mudanças são apenas api_key, base_url e model. O próprio SDK Python da OpenAI também permite configurar base_url ou OPENAI_BASE_URL (openai-python), e o campo correspondente no SDK Node é baseURL (openai-node).

Exemplo mínimo em Python:

from openai import OpenAI

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

resp = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[
        {"role": "system", "content": "你是一个简洁的技术助手。"},
        {"role": "user", "content": "用一句话解释什么是向量数据库。"},
    ],
)

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

Se o seu código antigo já usa client.chat.completions.create(), muito provavelmente você só precisa transformar a inicialização do client em itens de configuração. Não deixe o nome do modelo hardcoded dentro das funções de negócio; depois, mudar para Batch, Flex ou trocar de modelo vai doer mais.

No Node.js, a lógica é a mesma

Na versão JavaScript, basta trocar o nome do campo de base_url para baseURL:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.GEMINI_API_KEY,
  baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});

const resp = await client.chat.completions.create({
  model: "gemini-3.5-flash",
  messages: [{ role: "user", content: "给我一个 Redis 限流方案。" }],
});

console.log(resp.choices[0].message.content);

Também dá para chamar diretamente via REST: POST https://generativelanguage.googleapis.com/v1beta/openai/chat/completions, usando Authorization: Bearer $GEMINI_API_KEY no cabeçalho. Isso é útil para primeiro descartar problemas de SDK, proxy ou variáveis de ambiente com curl.

Não estime preço no chute: calcule pela saída

Em 14/06/2026, a página oficial de pricing do Gemini listava o preço padrão do gemini-3.5-flash como $1.50 / 1M tokens de entrada e $9.00 / 1M tokens de saída; Batch e Flex ficam em $0.75 / 1M tokens de entrada e $4.50 / 1M tokens de saída (pricing da Gemini API). A documentação também informa que o preço de saída inclui thinking tokens, então, em tarefas de raciocínio, não olhe apenas para o preço de entrada.

Modo	Entrada / 1M tokens	Saída / 1M tokens	Cenários adequados
Standard	$1.50	$9.00	Requisições online, baixa latência
Batch	$0.75	$4.50	Processamento em lote offline
Flex	$0.75	$4.50	Aceita agendamento flexível

Minha recomendação é simples: chat, Agent e plugins de editor devem começar em Standard; resumo de logs, limpeza de dados e avaliações offline devem ir, sempre que possível, para Batch/Flex. Em tarefas com saídas longas, a diferença de custo fica amplificada.

Armadilhas mais comuns na migração

Primeiro, não esqueça o /openai/ no final do base_url. Muitos erros 404 e mensagens de modelo inexistente acontecem porque a chamada foi para o caminho nativo do Gemini, não para o caminho de compatibilidade.
Segundo, separe bem as variáveis de ambiente. OPENAI_API_KEY pode continuar sendo usada para a OpenAI; para o Gemini, recomendo usar GEMINI_API_KEY separadamente, para evitar que dois providers disputem a mesma variável no CI.
Terceiro, rode models.list() antes. A documentação do Google traz exemplos para listar e obter modelos; antes de ir para produção, use isso para confirmar região da conta, permissões e IDs dos modelos.
Quarto, streaming, function calling e entrada de imagens têm exemplos na camada de compatibilidade, mas não assuma que todos os parâmetros da OpenAI são compatíveis um a um. Faça uma regressão com uma requisição real do seu negócio primeiro.

Se você quiser manter menos chaves

Se a equipe usa Claude, GPT e Gemini ao mesmo tempo, solicitar acesso, cadastrar cartão e configurar limites um por um é bem chato. O caminho mais prático é usar a onehop: troque o base_url do SDK da OpenAI para https://api.onehop.ai/v1, use a chave da onehop e você consegue chamar Claude, GPT e Gemini por interfaces compatíveis com OpenAI/Anthropic. A proposta dela é reduzir o trabalho de integração; os preços são menores que os oficiais, novas contas recebem $10 e não é preciso cadastrar cartão.

from openai import OpenAI

client = OpenAI(
    api_key="ONEHOP_API_KEY",
    base_url="https://api.onehop.ai/v1",
)

resp = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[{"role": "user", "content": "把这段报错日志总结成三条原因。"}],
)

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

Se quiser testar Claude ou roteamento multimodelo, veja diretamente: chamar Claude e outros modelos pela onehop. Se quiser primeiro rodar um exemplo pequeno sem cadastrar cartão, use esta entrada: cadastre-se e receba $10 em créditos de teste.

Conclusão: transforme em configuração, não fixe o fornecedor no código

O maior valor desta compatibilidade do Gemini com OpenAI não é “mais um modelo”, mas o custo de migração suficientemente baixo. Coloque base_url, api_key e model na configuração, e deixe o código de negócio continuar usando chat completions do SDK da OpenAI.
Depois de fazer rodar, complemente com três coisas: registre tokens de entrada/saída, escolha Standard ou Batch/Flex conforme a tarefa e transforme o ID do modelo em uma chave de rollout gradual. Assim, se hoje você integrar o Gemini e amanhã integrar Claude ou outro serviço compatível, não precisará mais mexer no código central do negócio.