Se você já usa o SDK da OpenAI, a maneira mais rápida de testar o Gemini é alterar a chave da API, a URL base e o ID do modelo. A URL base oficial compatível com OpenAI da API Gemini é:
https://generativelanguage.googleapis.com/v1beta/openai/
Para o Flatkey, a URL base do router compatível com OpenAI é:
https://router.flatkey.ai/v1
Esse é o núcleo da Configuração da URL Base Compatível com OpenAI da Gemini API e do Router Flatkey: o Gemini direto usa uma chave de API do Google e o endpoint compatível com OpenAI do Google; o Flatkey usa uma chave Flatkey, o router Flatkey e um ID de modelo Gemini disponível na sua conta Flatkey.
Use a rota direta do Google quando você só precisa do Gemini e quer a configuração mais próxima possível do provedor específico. Use a rota Flatkey quando você já estiver comparando o Gemini com GPT, Claude, DeepSeek, Qwen ou outros modelos e quiser uma única URL base compatível com OpenAI, uma lista de modelos e um único log de uso.
Configuração da URL Base Compatível com OpenAI da Gemini API e do Router Flatkey em resumo
| Opção de configuração | URL base | Chave de API | Origem do ID do modelo | Melhor opção para |
|---|---|---|---|---|
| Gemini direto | https://generativelanguage.googleapis.com/v1beta/openai/ |
Chave da API Gemini | Documentação dos modelos da API Gemini do Google ou client.models.list() |
Você só precisa do Gemini e quer acesso direto ao Google. |
| Router Flatkey | https://router.flatkey.ai/v1 |
Chave da API Flatkey | /v1/models do Flatkey ou o Diretório de Modelos |
Você quer o Gemini ao lado de outros provedores de modelo atrás de uma única chave. |
Não misture os dois. Uma chave de API do Gemini não autenticará no Flatkey, e uma chave Flatkey não autenticará no endpoint direto do Gemini do Google.
Configuração direta do Gemini com o SDK da OpenAI
A camada de compatibilidade com OpenAI do Google permite que você mantenha a mesma estrutura do SDK da OpenAI para fluxos comuns de conclusão de chat. A diferença importante é a configuração do cliente.
Python
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.8-flash",
messages=[
{"role": "user", "content": "Escreva uma frase sobre roteamento de modelos."}
],
)
print(response.choices[0].message.content)
JavaScript
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.GEMINI_API_KEY,
baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});
const response = await client.chat.completions.create({
model: "gemini-3.8-flash",
messages: [
{ role: "user", content: "Escreva uma frase sobre roteamento de modelos." },
],
});
console.log(response.choices[0].message.content);
REST
curl https://generativelanguage.googleapis.com/v1beta/openai/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $GEMINI_API_KEY" \
-d '{
"model": "gemini-3.8-flash",
"messages": [
{"role": "user", "content": "Escreva uma frase sobre roteamento de modelos."}
]
}'
Antes de fazer o deploy, execute client.models.list() ou GET /openai/models usando a mesma URL base. Isso detecta o erro mais comum: copiar um ID de modelo antigo de um post de blog e assumir que ele ainda existe para a sua conta.
Configuração do router Flatkey para Gemini
A Flatkey mantém a mesma estrutura do SDK da OpenAI, mas a URL base e a chave mudam novamente. Você usa o router Flatkey e depois escolhe um ID de modelo Gemini a partir da resposta de /v1/models da Flatkey ou do Model Directory ao vivo.
Python
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["FLATKEY_API_KEY"],
base_url="https://router.flatkey.ai/v1",
)
models = client.models.list()
gemini_models = [model.id for model in models.data if "gemini" in model.id]
print(gemini_models)
response = client.chat.completions.create(
model=os.environ.get("FLATKEY_GEMINI_MODEL", "gemini-2.5-flash"),
messages=[
{"role": "user", "content": "Escreva uma frase sobre roteamento de modelos."}
],
)
print(response.choices[0].message.content)
JavaScript
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.FLATKEY_API_KEY,
baseURL: "https://router.flatkey.ai/v1",
});
const models = await client.models.list();
console.log(models.data.map((model) => model.id).filter((id) => id.includes("gemini")));
const response = await client.chat.completions.create({
model: process.env.FLATKEY_GEMINI_MODEL || "gemini-2.5-flash",
messages: [
{ role: "user", content: "Escreva uma frase sobre roteamento de modelos." },
],
});
console.log(response.choices[0].message.content);
Em produção, não assuma que o ID de modelo direto do Google e o ID de modelo roteado da Flatkey serão sempre idênticos. Trate a lista de modelos como a fonte da verdade para a conta que você está chamando.
Variáveis de ambiente para manter a troca reversível
Uma configuração limpa da URL Base Compatível com OpenAI da Gemini API e do Router Flatkey deve facilitar a comparação entre testes diretos e roteados sem editar o código da aplicação.
# Gemini direto
GEMINI_API_KEY="..."
GEMINI_OPENAI_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"
GEMINI_MODEL="gemini-3.8-flash"
# Router Flatkey
FLATKEY_API_KEY="..."
FLATKEY_BASE_URL="https://router.flatkey.ai/v1"
FLATKEY_GEMINI_MODEL="gemini-2.5-flash"
Depois selecione a rota a partir da configuração:
import os
from openai import OpenAI
route = os.environ.get("AI_ROUTE", "flatkey")
if route == "direct_gemini":
client = OpenAI(
api_key=os.environ["GEMINI_API_KEY"],
base_url=os.environ["GEMINI_OPENAI_BASE_URL"],
)
model = os.environ["GEMINI_MODEL"]
else:
client = OpenAI(
api_key=os.environ["FLATKEY_API_KEY"],
base_url=os.environ["FLATKEY_BASE_URL"],
)
model = os.environ["FLATKEY_GEMINI_MODEL"]
response = client.chat.completions.create(
model=model,
messages=[{"role": "user", "content": "Retorne exatamente: route ok"}],
)
Esse padrão permite que um indie hacker teste primeiro o Gemini direto, adicione o Flatkey depois e faça rollback sem reescrever o caminho da requisição.
Checklist de smoke test antes de mover o tráfego
| Check | Gemini direto | Router Flatkey |
|---|---|---|
| Autenticação | Confirme que a chave do Gemini funciona apenas no endpoint do Google. | Confirme que a chave do Flatkey funciona apenas em router.flatkey.ai. |
| Lista de modelos | Execute client.models.list() na base URL do Gemini. |
Execute client.models.list() no Flatkey e filtre pelos IDs do Gemini. |
| Chat básico | Envie uma conclusão de chat curta sem streaming. | Envie o mesmo prompt pelo modelo Gemini do Flatkey. |
| Streaming | Teste streaming apenas se seu app usar streaming. | Teste streaming no modelo roteado exato antes de habilitá-lo para usuários. |
| Chamada de ferramentas | Teste um pequeno schema de função se seu app usar ferramentas. | Confirme que o modelo roteado suporta o comportamento de ferramentas que seu app espera. |
| Saída estruturada | Valide a saída JSON real, não apenas o status 200. |
Valide o mesmo schema e o mesmo comportamento de retry. |
| Revisão de uso | Verifique o uso e os erros do Google na sua conta do provedor. | Verifique os Usage Logs do Flatkey para modelo, contagem de tokens, latência e custo. |
Compatível com OpenAI não significa que todo recurso específico de um provedor se comporte de forma idêntica. Significa que a estrutura do seu cliente pode ficar próxima o suficiente para fluxos comuns do SDK. O smoke test deve cobrir os recursos dos quais seu app realmente depende.
Erros comuns de base URL
Esquecer /openai/ na rota direta do Gemini
Para chamadas diretas do Gemini compatíveis com OpenAI, use:
https://generativelanguage.googleapis.com/v1beta/openai/
Não use o endpoint nativo do Gemini generateContent com código de chat completion do SDK OpenAI. Exemplos nativos da API Gemini e exemplos compatíveis com OpenAI têm formatos de requisição diferentes.
Usar base_url no Node ou baseURL em Python
A configuração do SDK OpenAI em Python usa base_url. O SDK JavaScript usa baseURL.
OpenAI(base_url="https://router.flatkey.ai/v1")
new OpenAI({ baseURL: "https://router.flatkey.ai/v1" })
Tratar IDs de modelo como permanentes
Os nomes dos modelos mudam mais rápido do que o código de configuração do SDK. Para o caminho direto, consulte a documentação de modelos do Google ou liste os modelos pelo endpoint OpenAI-compatible da Gemini. Para o Flatkey, verifique /v1/models e o Model Directory.
Skipping logs
A primeira resposta bem-sucedida não é o fim da configuração. Depois da primeira solicitação ao Flatkey, abra os Usage Logs e verifique o modelo, as contagens de tokens, a latência e o custo. Isso torna a configuração da URL Base Compatível com OpenAI da Gemini API e do Router Flatkey rastreável operacionalmente, e não apenas sintaticamente correta.
Quando a Flatkey agrega valor
O Flatkey é útil quando a Gemini é apenas um caminho em uma pilha mais ampla de modelos. Por exemplo:
- Você quer Gemini, Claude, GPT, DeepSeek e Qwen atrás de uma única URL base compatível com OpenAI.
- Você está testando o comportamento de fallback de modelos e não quer chaves de provedores separadas espalhadas por apps e agentes.
- Você precisa de um registro compartilhado de uso para IDs de modelo, contagens de tokens, latência e custo por solicitação.
- Você quer que os desenvolvedores alterem o parâmetro de modelo sem mudar o cliente do SDK.
Se o seu app só for chamar a Gemini, a configuração direta do Google pode ser suficiente. Se o seu produto já estiver comparando provedores, o router Flatkey oferece um caminho de migração mais limpo.
Links internos úteis para manter abertos
- Introdução rápida à API Flatkey
- Guia de migração compatível com OpenAI
- Verificações de rota Gemini vs Claude
- Diretório de Modelos do Flatkey
- Página de preços do Flatkey
- Página de status do Flatkey
Perguntas frequentes
What is the official Gemini OpenAI-compatible base URL?
A URL base oficial compatível com OpenAI da Gemini é https://generativelanguage.googleapis.com/v1beta/openai/. Use-a com uma chave de API da Gemini, não com uma chave do Flatkey.
What base URL should I use for Gemini through Flatkey?
Use https://router.flatkey.ai/v1 com uma chave de API do Flatkey. Em seguida, escolha um ID de modelo da Gemini a partir da resposta de /v1/models do Flatkey ou do Model Directory ao vivo.
Can I use the same Gemini model ID in both places?
Às vezes, mas não presuma isso. O processo seguro é listar os modelos para a rota exata e a conta que você está usando e, então, fixar esse ID na configuração.
Does OpenAI-compatible mean full feature parity?
Não. Trate a compatibilidade com OpenAI como uma conveniência de SDK e de formato da requisição. Teste streaming, tools, structured output, files e entradas multimodais no modelo e na rota exatos antes do lançamento em produção.
Should an indie hacker start direct or with Flatkey?
Comece direto se você estiver apenas comprovando que a Gemini funciona. Comece com o Flatkey se a decisão real for qual modelo deve alimentar o produto, e não se a Gemini sozinha consegue responder ao prompt.
Conclusão
A configuração da URL Base Compatível com OpenAI da Gemini API e do Router Flatkey é simples quando você separa os dois caminhos:
- Gemini direta:
https://generativelanguage.googleapis.com/v1beta/openai/ - Router Flatkey:
https://router.flatkey.ai/v1
Mantenha as chaves separadas, liste os modelos antes de chamar as completions de chat, teste os recursos que seu aplicativo usa e verifique o uso após a primeira solicitação. Quando estiver pronto para comparar o Gemini com outros provedores por meio de uma camada compatível com OpenAI, crie uma chave Flatkey e mova uma carga de trabalho de cada vez.
