Acesso compatível com OpenAI da Gemini API é útil para dois caminhos diferentes de migração. O Google documenta um endpoint direto compatível com OpenAI para Gemini, e a Flatkey oferece às equipes um caminho de roteador quando elas querem acesso ao Gemini dentro do mesmo gateway de chave única que usam para outros modelos.
O caminho direto do Google é uma troca de URL base para https://generativelanguage.googleapis.com/v1beta/openai/ com uma chave da API Gemini. O caminho da Flatkey mantém a estrutura do SDK OpenAI, mas aponta seu cliente para https://router.flatkey.ai/v1, usa uma chave da Flatkey e seleciona um ID de modelo Gemini do catálogo da Flatkey antes de testar logs, custo e suporte a recursos.
Este guia explica como usar com segurança uma rota compatível com OpenAI da Gemini API. Ele cobre o que a documentação de compatibilidade do Google realmente suporta, onde um roteador altera o modelo operacional e o que verificar antes de mover o tráfego de produção.
Resposta Rápida: Roteamento Compatível com a API OpenAI do Gemini
Se seu app já usa o SDK Python ou JavaScript da OpenAI, uma migração compatível com a API OpenAI do Gemini começa pela configuração, não por uma reescrita.
| Decisão | Gemini API Direta | Gemini Através do Flatkey |
|---|---|---|
| Chave de API | Chave da API Gemini do Google AI Studio | Chave da API Flatkey |
| URL base | https://generativelanguage.googleapis.com/v1beta/openai/ |
https://router.flatkey.ai/v1 |
| Objetivo principal | Chamar o Gemini usando a sintaxe do SDK da OpenAI | Roteie o Gemini junto de outros provedores de modelo atrás de uma única chave |
| Escolha de modelo | ID do modelo Gemini da Google a partir da documentação do Google | ID do modelo Gemini do Flatkey a partir da tabela de preços ou do painel |
| Validação | Resposta, comportamento do modelo, faturamento do Google | Resposta, log de uso do Flatkey, unidade de preço, cota, rollback |
Use o endpoint direto do Google quando você precisar apenas do Gemini e quiser controle de conta nativo do provedor. Use o roteador do Flatkey quando o Gemini precisar ficar ao lado de GPT, Claude, DeepSeek, Qwen, imagem, vídeo e outros acessos a modelos atrás de uma única chave, um único painel e uma única superfície de faturamento.
O que a documentação de compatibilidade da OpenAI do Google confirma
A documentação de compatibilidade com OpenAI do Google diz que os modelos Gemini podem ser acessados com as bibliotecas OpenAI para Python e JavaScript, além de REST, atualizando a chave de API, a URL base e o modelo. A URL base direta documentada é https://generativelanguage.googleapis.com/v1beta/openai/.
A mesma página mostra exemplos de conclusões de chat, respostas em streaming, chamada de funções, compreensão de imagens e embeddings. Ela também observa que o upload e o download de arquivos compatíveis com OpenAI não são suportados no momento, então os fluxos de trabalho com arquivos precisam do tratamento do cliente Google GenAI em vez de assumir paridade total de arquivos com a OpenAI.
Essa é a principal lição para qualquer guia Gemini API OpenAI compatible: a compatibilidade é específica do endpoint e do recurso. Uma conclusão de chat pode ser uma migração limpa da URL base, enquanto fluxos de upload de arquivos, imagem, lote, ferramentas ou embeddings ainda merecem seus próprios testes.
Onde o Flatkey muda a configuração do Gemini
O Flatkey não pede que você substitua um app compatível com OpenAI por um novo SDK de provedor para o primeiro teste. A superfície pública do produto Flatkey é construída em torno de uma única chave de API, sem contas separadas de provedor, preços claros, cobrança unificada e um único painel para chaves, uso e roteamento. Ele também mostra a URL base do roteador compatível com OpenAI como https://router.flatkey.ai/v1.
Para uma rota Gemini API OpenAI compatible através do Flatkey, a mudança importante não é o nome do método do SDK OpenAI. A mudança importante é operacional:
- Você seleciona um ID de modelo Gemini no Flatkey, e não apenas na documentação do Google.
- Você verifica uso e custo no Flatkey após a requisição, e não apenas na resposta do aplicativo.
- Você mantém o Gemini dentro do mesmo fluxo de roteamento e cota que outros provedores.
- Você evita criar um caminho separado de conta de provedor para cada equipe ou ferramenta.
- Você mantém o rollback simples controlando URL base, chave e modelo por meio de configuração.
O snapshot de preços ao vivo do Flatkey verificado para este artigo incluía linhas de catálogo com nome Gemini, mas a disponibilidade e os nomes exatos dos modelos podem mudar. Trate o catálogo como a fonte de verdade do dia da publicação: escolha o modelo em pricing ou no painel e, em seguida, teste o ID exato do modelo antes do tráfego de produção.
Padrão de Migração da Base URL
Comece separando a migração em três variáveis de ambiente:
FLATKEY_API_KEY="sk-fk-your-key"
OPENAI_BASE_URL="https://router.flatkey.ai/v1"
FLATKEY_GEMINI_MODEL="replace-with-flatkey-gemini-model-id"Isso lhe dá uma troca limpa para qualquer cliente Gemini API OpenAI compatible. O código do app mantém o caminho do SDK compatível com OpenAI. A configuração decide se a requisição vai diretamente para o Google, para a Flatkey ou para outro endpoint compatível.
| Config Item | Why It Matters | What To Avoid |
|---|---|---|
| Base URL | Keep the router choice outside business logic. | Hardcoding provider URLs in many files. |
| API key | Separates direct provider credentials from router credentials. | Reusing old provider keys for a Flatkey route. |
| Model ID | Allows you to deliberately map a Google model to a Flatkey catalog model. | Assuming every provider model alias exists behind the router. |
| Rollback values | Lets you restore the previous route quickly. | Making rollback require a code deploy. |
Modelo Python para Roteamento Flatkey Gemini
Apenas um modelo: execute isto com uma chave Flatkey válida e um ID de modelo Flatkey Gemini confirmado antes de usá-lo em produção.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["FLATKEY_API_KEY"],
base_url=os.environ.get("OPENAI_BASE_URL", "https://router.flatkey.ai/v1"),
)
response = client.chat.completions.create(
model=os.environ["FLATKEY_GEMINI_MODEL"],
messages=[
{
"role": "user",
"content": "Responda com uma frase confirmando que a rota Gemini está configurada.",
}
],
)
print(response.choices[0].message.content)
print(response.usage)O método do SDK da OpenAI é familiar, mas não trate isso como uma migração concluída compatível com Gemini API OpenAI até que o log de uso da Flatkey mostre a requisição, o modelo, o uso de tokens, o status e o custo.
Modelo JavaScript para Roteamento Flatkey Gemini
Apenas modelo: execute com uma chave Flatkey válida e um ID de modelo confirmado do catálogo atual da Flatkey.
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.FLATKEY_API_KEY,
baseURL: process.env.OPENAI_BASE_URL || "https://router.flatkey.ai/v1",
});
const response = await client.chat.completions.create({
model: process.env.FLATKEY_GEMINI_MODEL,
messages: [
{
role: "user",
content: "Responda com uma frase confirmando que a rota Gemini está configurada.",
},
],
});
console.log(response.choices[0].message.content);
console.log(response.usage);Para equipes que já usam SDKs compatíveis com OpenAI, isso mantém a migração pequena. O trabalho de produção está na validação de recursos, mapeamento de modelos, cotas e verificações de faturamento.
Lista de Verificação de Funcionalidades Antes da Produção
Use esta lista de verificação antes de considerar uma rota compatível com Gemini API OpenAI como pronta.
| Funcionalidade | Sinal nos Documentos do Google | Verificação do Flatkey Router |
|---|---|---|
| Completions de chat básicas | Exemplos de OpenAI SDK e REST estão documentados. | Confirme a resposta e o registro de uso do Flatkey. |
| Streaming | O Google documenta streaming com chamadas no estilo OpenAI. | Teste o tratamento de stream, timeout e análise de saída parcial. |
| Chamada de função | O Google documenta chamada de ferramenta/função por meio de exemplos de compatibilidade. | Teste o esquema exato da sua ferramenta e o comportamento da escolha da ferramenta. |
| Compreensão de imagem | O Google documenta entrada de imagem por meio de completions de chat. | Confirme que o modelo Flatkey aceita o formato de imagem que seu SDK envia. |
| Embeddings e lote | O Google documenta embeddings e exemplos relacionados a lote. | Teste como um caminho de endpoint separado, não como uma suposição de chat. |
| Upload/download de arquivos | O Google diz que upload/download compatível com OpenAI não é suportado no momento. | Use um plano de arquivos nativo de um provedor separado se o seu fluxo de trabalho depender de arquivos. |
| Preços | O Google mantém uma página de preços da Gemini Developer API. | Use os preços do Flatkey para o uso roteado e, depois, verifique os registros reais de custo. |
Runbook de Smoke Test
Um smoke test compatível com a API OpenAI do Gemini deve comprovar tanto o comportamento da API quanto a visibilidade do roteador.
- Escolha um ID de modelo Gemini do catálogo atual da Flatkey.
- Crie ou selecione uma chave Flatkey de baixo risco para testes.
- Defina
OPENAI_BASE_URLcomohttps://router.flatkey.ai/v1. - Execute um prompt simples de chat sem streaming.
- Confirme que a forma da mensagem do assistant corresponde ao parser do seu app.
- Verifique nos logs de uso da Flatkey o modelo, o status, os tokens e o custo.
- Execute um teste de modelo inválido e registre a forma do erro.
- Execute streaming, chamadas de ferramentas, visão ou embeddings somente se seu app os usar.
- Defina uma pequena cota antes que qualquer tráfego real seja enviado.
- Mantenha a URL base do provedor anterior e o modelo como configuração de rollback.
O objetivo não é apenas fazer uma resposta do Gemini aparecer. O objetivo é saber para onde a rota foi, quanto custou, como as falhas se apresentam e com que rapidez você consegue fazer rollback.
Erros Comuns
- Usar a URL base direta do Gemini compatível com OpenAI da Google quando você pretendia testar o Flatkey.
- Usar um ID de modelo do Google sem confirmar a string do modelo no catálogo do Flatkey.
- Assumir que o upload/download de arquivos funciona por todos os caminhos compatíveis com OpenAI.
- Testar apenas chat completions quando a produção usa streaming ou tools.
- Ignorar a verificação do usage-log e da cobrança após uma resposta bem-sucedida.
- Publicar snippets de código com chaves que parecem reais ou IDs de modelo de produção não testados.
Esses são detalhes pequenos, mas é neles que a maioria das migrações Gemini API OpenAI compatible falha. Um roteador facilita o acesso; ele não elimina a necessidade de testar a forma exata da requisição.
Como Isto Se Encaixa com os Guias de Migração Flatkey Existentes
Se esta é a sua primeira migração de roteador, comece com o guia mais amplo de migração da API compatível com OpenAI. Ele cobre o padrão de URL base, variáveis de ambiente, testes rápidos, rollback e verificações do dashboard que se aplicam a qualquer provedor.
Depois, use este guia específico do Gemini para os detalhes do provedor: o endpoint de compatibilidade direta do Google, a seleção de modelos Gemini, o suporte a recursos e as limitações de tratamento de arquivos. Para padrões adjacentes de acesso a modelos, compare o guia de acesso à API do DeepSeek e o guia proxy vs roteador da API do Claude.
FAQ
O Gemini API é compatível com OpenAI?
O Google documenta a compatibilidade com OpenAI para o Gemini por meio das bibliotecas OpenAI Python e JavaScript, além de exemplos REST. Isso não significa que todos os endpoints ou parâmetros do OpenAI tenham comportamento idêntico, então teste exatamente o recurso que seu app usa.
Qual é a URL base direta do Gemini OpenAI?
A URL base direta compatível com OpenAI documentada pelo Google é https://generativelanguage.googleapis.com/v1beta/openai/. Use essa URL ao chamar o Google diretamente com uma chave de API do Gemini.
Qual URL base devo usar para o Gemini via Flatkey?
Use https://router.flatkey.ai/v1 para uma rota Flatkey compatível com OpenAI. Depois, escolha um ID de modelo Gemini no preço do Flatkey ou no painel e teste a solicitação antes da produção.
Posso usar o mesmo ID de modelo da documentação do Google no Flatkey?
Não automaticamente. As strings de modelo e a disponibilidade podem variar conforme o catálogo e a rota. Escolha o ID do modelo no Flatkey no dia em que você testar e mantenha-o na configuração.
Compatível com OpenAI significa paridade total de recursos?
Não. Compatível com OpenAI geralmente significa que formatos comuns de solicitação e resposta funcionam para endpoints suportados. O Google observa especificamente que upload e download compatíveis com OpenAI não são suportados no momento, então é necessário testar no nível do recurso.
Como devo planejar o orçamento do Gemini por meio de um roteador?
Use a documentação de preços do Google para o contexto direto do Gemini e os preços do Flatkey para uso roteado. Em seguida, verifique o custo real da solicitação nos logs do Flatkey, porque modelo, cache, lote e unidades de modalidade podem diferir.
Veja os preços antes de rotear o tráfego de produção
Gemini API OpenAI compatible é um caminho prático de migração quando seu app já usa chamadas de SDK no estilo OpenAI. Mantenha a mudança pequena: atualize a URL base, use uma chave Flatkey, selecione um modelo Gemini atual, execute os testes smoke e verifique o uso e os preços antes do rollout.
Ver preços para confirmar as opções atuais de modelo Gemini da Flatkey e as unidades de custo antes de enviar tráfego de produção.
