Usando o OpenAI SDK para chamar a Gemini API: tutorial de migração alterando apenas base_url, API Key e nome do modelo

Em 2026-06-14, a documentação de compatibilidade do Gemini com OpenAI do Google é bem direta: se você já tem código usando as bibliotecas OpenAI em Python ou TypeScript, pode conectar ao Gemini alterando a API Key, o base_url e o nome do modelo; o modelo usado nos exemplos da documentação é gemini-3.5-flash, e a página de compatibilidade foi atualizada pela última vez em 2026-05-18 (Google AI for Developers). Isso não é “mágica de camada de adaptação”; é apenas enviar as requisições do SDK da OpenAI para o endpoint compatível fornecido pelo Google.

Instale o SDK primeiro, sem mudar o paradigma de chamada

Se o seu projeto já usa o SDK oficial da OpenAI para Python, basta manter chat.completions.create(). O repositório do SDK Python da OpenAI continua sendo a fonte oficial do cliente (openai-python), e a interface compatível do Google também aceita esse formato de chamada.

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": "You are a concise code reviewer."},
        {"role": "user", "content": "Review this Python function for edge cases."},
    ],
)

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

A API Key é criada no Google AI Studio (chave de API do AI Studio). Preste atenção à barra final: /v1beta/openai/, não o endpoint nativo comum do Gemini, como /v1beta/models/....

REST também pode seguir o formato da OpenAI

Para servidor, depuração com curl e health checks de gateway, você não precisa necessariamente usar um SDK. O caminho REST indicado pela documentação de compatibilidade do Google é /openai/chat/completions:

curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.5-flash",
    "messages": [
      {"role": "user", "content": "Give me a 5-point migration checklist."}
    ]
  }'

Durante a migração, execute esse comando primeiro. Ele ajuda a separar quatro tipos de problema — Key, nome do modelo, saída de rede e permissões de faturamento — e economiza tempo em comparação com debugar diretamente dentro do serviço de produção.

Como o reasoning_effort é mapeado

O controle de thinking do Gemini e o reasoning_effort da OpenAI têm sobreposição, e o Google afirma claramente que os dois não devem ser enviados ao mesmo tempo. A camada compatível mapeia os parâmetros no estilo OpenAI para os parâmetros de thinking do Gemini (compatibilidade Google OpenAI).

OpenAI reasoning_effort	Gemini 3 thinking_level	Gemini 2.5 thinking_budget
minimal	minimal ou low	1024
low	low	1024
medium	medium	8192
high	high	24576

Para uma migração conservadora, primeiro não envie reasoning_effort e deixe o modelo usar o valor padrão. Para controlar custos, adicione low em tarefas com contexto longo e observe depois a qualidade da saída e a cobrança de tokens.

Não olhe apenas para o nome do modelo ao avaliar preço

A página oficial de preços do Google lista de forma clara os preços padrão do Gemini 2.5 Pro e Flash, em unidades por 1 milhão de tokens, e o preço de saída inclui thinking tokens (preços da API Gemini).

Modelo	Preço de entrada	Preço de saída
gemini-2.5-pro, prompt ≤ 200k	$1.25	$10.00
gemini-2.5-pro, prompt > 200k	$2.50	$15.00
gemini-2.5-flash, entrada de texto/imagem/vídeo	$0.30	$2.50
gemini-2.5-flash, entrada de áudio	$1.00	$2.50

Minha sugestão: para chat, classificação e tarefas leves de código, comece com Flash; para raciocínio complexo, síntese de documentos longos e refatoração de código, mude para Pro. O limite de 200k de prompt do Pro afeta diretamente os preços de entrada e saída; não jogue logs, trechos recuperados e prompts de system repetidos tudo de uma vez.

Checklist de migração

1. Troque OPENAI_API_KEY por GEMINI_API_KEY, gerada no AI Studio.
2. Altere o base_url para https://generativelanguage.googleapis.com/v1beta/openai/.
3. Troque o nome do modelo para um modelo Gemini compatível, como gemini-3.5-flash.
4. Primeiro valide com REST curl; depois conecte de volta ao SDK.
5. Suspenda o reasoning_effort personalizado e adicione novamente só depois de confirmar a qualidade.
6. Registre custos de tokens de entrada, saída e thinking, especialmente o limite de 200k do Pro.

Se você também precisa conectar Claude/GPT

Se for usar apenas Gemini, o caminho mais limpo é usar o endpoint compatível oficial do Google. Mas, quando o projeto precisa ao mesmo tempo de Claude, GPT e Gemini, lidar com várias Keys, várias cobranças e vários SDKs fica bem chato. O caminho mais simples é a onehop: compatível com OpenAI/Anthropic, basta alterar o base_url para https://api.onehop.ai/v1 e usar o mesmo SDK da OpenAI para chamar Claude/GPT/Gemini; ela destaca preços inferiores aos oficiais, $10 para novas contas e ausência de necessidade de 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="anthropic/claude-sonnet-4.5",
    messages=[{"role": "user", "content": "Refactor this API handler."}],
)
print(resp.choices[0].message.content)

Se agora você só quer colocar o acesso multimodelo para funcionar, pode testar diretamente: chamar Claude e outros modelos pela onehop, ou primeiro resgatar créditos: cadastre-se e ganhe $10 em créditos de teste. O ponto-chave da migração não é trocar um monte de camadas abstratas, mas reduzir as variáveis a três coisas: endpoint, key e model.