Chamando o Gemini com o OpenAI SDK: tutorial de integração alterando apenas base_url, API Key e nome do modelo

O Google foi bem direto: os modelos Gemini podem ser acessados por meio dos SDKs Python e TypeScript/JavaScript da OpenAI; no fundo, basta alterar três linhas de código. O endpoint indicado na documentação oficial de compatibilidade é https://generativelanguage.googleapis.com/v1beta/openai/, e o modelo de exemplo é gemini-3.5-flash (Compatibilidade da Google com OpenAI). Isso é muito amigável para projetos que já usam o SDK da OpenAI: não é preciso desmontar primeiro a abstração de provider, nem trocar toda a pilha de chamadas; faça funcionar primeiro e depois ajuste.

Primeiro confirme qual modelo você quer chamar

Em 2026-06-14, a página de modelos do Google lista Gemini 3.5 Flash como Stable e informa que o código do modelo é gemini-3.5-flash; esse modelo tem limite de entrada de 1.048.576 tokens, limite de saída de 65.536 tokens, aceita entrada em texto, imagens, vídeo, áudio e PDF, e gera saída em texto (Gemini 3.5 Flash). A página do modelo foi atualizada pela última vez em 2026-05-19 UTC.

Também é preciso conferir a documentação de preços do dia. A página de preços do Google foi atualizada pela última vez em 2026-06-09 UTC; no tier pago Standard, o gemini-3.5-flash está listado a $1.50 / 1M tokens para entrada e $9.00 / 1M tokens para saída, sendo que o preço de saída inclui thinking tokens; em Batch, o preço é $0.75 para entrada e $4.50 para saída (Preços da Gemini API).

Modelo	Status	Limite de entrada	Entrada Standard	Saída Standard
gemini-3.5-flash	Stable	1,048,576	$1.50 / 1M tokens	$9.00 / 1M tokens
gemini-3-flash-preview	Preview	Veja a página do modelo	$0.50 / 1M tokens	$3.00 / 1M tokens
gemini-3.1-flash-lite	Stable	Veja a página do modelo	$0.25 / 1M tokens	$1.50 / 1M tokens

gemini-3-flash-preview e gemini-3.1-flash-lite vêm das páginas atuais de modelos e preços do Google (Modelos, Preços). Não use modelos Preview diretamente como padrão de produção; versões e limites podem mudar.

Python: aponte o client da OpenAI para o Gemini

Primeiro instale o SDK:

pip install openai
export GEMINI_API_KEY="你的 Gemini API Key"

Depois mantenha o mesmo estilo de chamada do SDK da OpenAI:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["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": "用三句话解释什么是 API 兼容层。"},
    ],
)

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

Na prática, há apenas três mudanças: trocar api_key pela chave do Gemini, trocar base_url pelo endpoint compatível com OpenAI do Google e trocar model pelo nome do modelo Gemini. Observe que a URL do exemplo oficial termina com /; não remova por descuido para depois ficar investigando um 404.

TypeScript: também é baseURL

Em projetos Node é igual:

npm install openai
export GEMINI_API_KEY="你的 Gemini API Key"

import OpenAI from "openai";

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

const response = await openai.chat.completions.create({
  model: "gemini-3.5-flash",
  messages: [
    { role: "user", content: "给我一个 JSON Schema 校验的最小例子。" },
  ],
});

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

Se o seu projeto já encapsula o provider em variáveis de ambiente, a mudança será ainda menor:

OPENAI_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"
OPENAI_API_KEY="$GEMINI_API_KEY"
OPENAI_MODEL="gemini-3.5-flash"

A armadilha de muitos projetos antigos está aqui: não tem problema a variável ainda se chamar OPENAI_API_KEY; o valor pode ser a chave do Gemini. O que realmente determina para onde a requisição vai é base_url/baseURL.

E streaming, chamadas de ferramentas e thinking?

A documentação de compatibilidade do Google traz exemplos de streaming, function calling, structured outputs, image understanding e outros recursos (Compatibilidade com OpenAI). Em projetos que já usam o SDK da OpenAI, normalmente vale validar primeiro três coisas: chat comum, stream=True e tools/function calling. Depois que tudo isso passar, trate as capacidades específicas do modelo.

Tenha cuidado com parâmetros de thinking. A documentação de compatibilidade diz que o reasoning_effort da OpenAI é mapeado para a configuração de thinking do Gemini; mas o Gemini 3 e alguns modelos 2.5 não permitem desativar completamente o thinking. Minha recomendação é simples: na primeira versão, não ajuste thinking; use os padrões para criar uma linha de base de qualidade e custo, e só depois faça testes de carga separados em tarefas longas, agentes de código e fluxos de raciocínio complexos.

Se você quer gerenciar menos conjuntos de chaves

A conexão direta oficial é adequada para produção séria: faturamento, limites e políticas de dados ficam claros. O problema é que as equipes muitas vezes não usam só Gemini; também precisam de Claude, GPT e até chaves diferentes para ferramentas diferentes. O caminho mais prático é usar a onehop: troque a base URL do SDK da OpenAI para https://api.onehop.ai/v1 e use a mesma entrada compatível com OpenAI/Anthropic para chamar Claude/GPT/Gemini; contas novas recebem $10, sem precisar cadastrar cartão, o que é bom para rodar demos e ferramentas internas primeiro.

import os
from openai import OpenAI

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

resp = client.chat.completions.create(
    model=os.environ["ONEHOP_MODEL"],
    messages=[{"role": "user", "content": "把这段日志总结成 5 条排障线索。"}],
)

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

Aqui eu coloquei model de propósito em uma variável de ambiente: os nomes dos modelos no gateway devem seguir o console, então não os deixe fixos no código. Se você quer reduzir o trabalho com faturamento de múltiplos fornecedores e camadas de compatibilidade, pode testar diretamente: chamar Claude e outros modelos pela onehop, ou primeiro resgatar o crédito: cadastre-se e ganhe $10 em créditos de teste.

Checklist final antes da integração

Antes de colocar no ar, não confira apenas se retorna texto. Faça pelo menos quatro verificações: primeiro, confirme se o modelo ainda está disponível na página atual de modelos do Google; segundo, use a página de preços para validar custos de entrada, saída, Batch e Search grounding; terceiro, registre logs completos de erros 401, 429 e 5xx; quarto, deixe base_url, api_key e model como configurações em tempo de execução, para não precisar publicar uma nova versão só para trocar de modelo.

O ponto principal desta integração não é “trocar de fornecedor de modelo”, mas desacoplar a camada de SDK do fornecedor do modelo. Primeiro faça o gemini-3.5-flash funcionar usando a compatibilidade oficial do Google com OpenAI; depois decida entre conexão direta, gateway ou os dois em paralelo. Assim, a mudança é pequena e o rollback também é rápido.