Se o seu app já usa uma API compatível com OpenAI, migrar para a Flatkey não deve começar com uma reescrita. O caminho controlado é menor: obtenha uma chave Flatkey, aponte seu SDK compatível com OpenAI para https://router.flatkey.ai/v1, escolha um ID de modelo do catálogo da Flatkey e verifique a primeira solicitação em logs, cotas e faturamento antes de enviar tráfego real.
Esse é o valor prático de uma API compatível com OpenAI. Ela permite que uma equipe mantenha o mesmo modelo mental para solicitações comuns enquanto move o acesso ao provedor para trás de um gateway único. A cópia pública do produto da Flatkey é construída em torno desse movimento: uma chave de API, uma URL base, preços claros, faturamento unificado e um painel único para chaves, uso e roteamento.
Este guia mostra o runbook de migração. Ele cobre a mudança da URL base, exemplos de SDK, mapeamento de IDs de modelo, testes smoke, verificações de endpoint, revisão de logs de uso, configuração de cotas, verificação de faturamento e rollback. Use-o quando estiver migrando um fluxo de trabalho existente no estilo Chat Completions para a Flatkey ou padronizando uma stack mult modelo atrás de um único endpoint de API compatível com OpenAI.
Resposta Rápida: O que muda em uma migração para uma API compatível com OpenAI?
Para a maioria dos clientes de chat já compatíveis com OpenAI, a primeira migração é uma mudança de configuração, não uma reescrita da aplicação.
| Configuração | Antes | Com Flatkey |
|---|---|---|
| Chave de API | Chave específica do provedor para OpenAI, Gemini, DeepSeek ou proxy | Chave de API Flatkey |
| URL base | URL base padrão do provedor ou outra URL base compatível com OpenAI | https://router.flatkey.ai/v1 |
| Endpoint de chat | /v1/chat/completions |
/v1/chat/completions via Flatkey |
| Modelo | ID do modelo do provedor existente | ID do modelo Flatkey selecionado no preço/painel |
| Validação | Apenas uma resposta bem-sucedida | Resposta + log de uso + custo + cota + rollback |
A palavra importante é "compatível". Uma API compatível com OpenAI não garante que todos os provedores, modelos, endpoints e parâmetros se comportem exatamente como a OpenAI. Isso significa que a API segue o padrão de requisição e resposta da OpenAI o suficiente para que chamadas comuns do cliente funcionem quando a URL base, a chave e o modelo estão corretos. Sua lista de verificação de migração deve comprovar os recursos exatos que seu aplicativo usa.
Por que os endpoints compatíveis com OpenAI estão se tornando a camada de migração
Os resultados de busca para OpenAI compatible API são, em sua maioria, referências oficiais, documentação de provedores, plugins, documentação de servidores locais e perguntas da comunidade. Isso faz sentido. Os desenvolvedores não estão apenas perguntando "o que é compatível?" Eles estão tentando mover código entre provedores de modelos sem बदलar cada ponto de chamada.
A documentação do Gemini do Google mostra exemplos da biblioteca OpenAI que definem uma base URL compatível com OpenAI do Gemini e chamam completions de chat. A documentação oficial da API do DeepSeek mostra exemplos do SDK OpenAI com a base URL do DeepSeek e IDs de modelo como deepseek-chat e deepseek-reasoner. O padrão é claro: muitos provedores encontram os desenvolvedores onde seus SDKs existentes já estão.
O Flatkey usa a mesma ideia de migração para um objetivo diferente. Em vez de apontar a OpenAI compatible API de um provedor para uma conta de um provedor, o Flatkey oferece às equipes uma única base URL compatível com OpenAI para acesso a múltiplos modelos, faturamento unificado e visibilidade no painel.
Passo 1: Inventarie o Cliente que Você Já Tem
Antes de mudar a URL base, anote o que seu app atual realmente usa. Uma migração limpa de OpenAI compatible API começa pela forma real da chamada, não por um novo app de exemplo.
| Verificação | O que Registrar |
|---|---|
| SDK | Python, Node, HTTP direto, LangChain, LiteLLM, Vercel AI SDK, ou outro wrapper. |
| Endpoint | Chat Completions, Responses, embeddings, images, video, ou endpoint nativo do provedor. |
| ID do Modelo | String exata usada em produção e quaisquer modelos de fallback. |
| Forma da Mensagem | Prompts de sistema, mensagens de desenvolvedor, mensagens de ferramenta, conteúdo multimodal, ou apenas texto simples. |
| Parâmetros | Streaming, temperature, max tokens, tool calls, saída JSON, formato da resposta, seed, timeout, retries. |
| Observabilidade | Onde você vê latência, uso de tokens, IDs de solicitação, erros e custo hoje. |
| Rollback | Com que rapidez você pode restaurar a antiga chave de API/URL base/modelo. |
Esse inventário mantém a migração honesta. Se seu app envia apenas mensagens simples de chat, o primeiro teste do Flatkey pode continuar pequeno. Se seu app depende de streaming, chamadas de ferramenta, modo JSON, imagens, vídeo ou da API Responses, trate cada recurso como um teste de fumaça separado.
Passo 2: Coloque a URL base atrás de uma camada de configuração
Não espalhe a nova URL base compatível com OpenAI por toda a base de código. Coloque-a em uma variável de ambiente ou em uma factory do SDK.
Variáveis de ambiente recomendadas:
FLATKEY_API_KEY="sk-fk-your-key"
OPENAI_BASE_URL="https://router.flatkey.ai/v1"
FLATKEY_MODEL="replace-with-publish-day-model-id"
ROLLBACK_OPENAI_BASE_URL="https://api.openai.com/v1"
ROLLBACK_MODEL="your-previous-model-id"Usar OPENAI_BASE_URL costuma ser conveniente porque muitos wrappers de SDK já oferecem suporte a essa convenção. Usar FLATKEY_API_KEY e FLATKEY_MODEL mantém a nova credencial e a escolha do modelo explícitas.
É aqui que a Flatkey se encaixa na intenção de busca openai compatible base url. A migração deve ser revisável em um único diff: URL base, chave, modelo e etapas de verificação.
Etapa 3: Executar um teste rápido com Curl
Comece com uma solicitação HTTP direta antes de alterar sua aplicação. Isso isola problemas de chave, URL base, endpoint e ID do modelo.
Apenas modelo: o revisor deve executar com uma chave Flatkey válida e um ID de modelo confirmado da data de publicação.
curl -sS "https://router.flatkey.ai/v1/chat/completions" \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLATKEY_MODEL"'",
"messages": [
{
"role": "user",
"content": "Responda com uma frase confirmando que este teste rápido do Flatkey funcionou."
}
]
}'Um teste rápido útil comprova mais do que 200 OK. Para uma migração de API compatível com OpenAI, verifique:
- A resposta tem uma mensagem de assistente utilizável.
- O nome do modelo é aquele que você pretendia testar.
- O uso aparece no painel do Flatkey ou nos logs de uso.
- A contagem de tokens e o custo ficam visíveis o suficiente para a análise de faturamento.
- As mensagens de erro são compreensíveis se o ID do modelo ou a chave estiver errado.
- A URL base antiga e o modelo ainda podem ser restaurados rapidamente.
Etapa 4: Alterar a Configuração do SDK Python da OpenAI
Se o seu app Python já usa o SDK da OpenAI, mantenha a construção do cliente centralizada.
Apenas modelo: o revisor deve executar antes da publicaçã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_MODEL"],
messages=[
{
"role": "user",
"content": "Confirme se esta solicitação de API compatível com a OpenAI está sendo roteada através da Flatkey.",
}
],
)
print(response.choices[0].message.content)
print(response.usage)O detalhe em Python que importa é base_url. Em uma migração limpa para uma API compatível com a OpenAI, o código da aplicação não deve saber se a URL base aponta diretamente para a OpenAI, para um endpoint compatível de um provedor ou para a Flatkey. Ele deve chamar o cliente compartilhado e deixar a configuração escolher a rota.
Etapa 5: Alterar a configuração do OpenAI SDK para Node
Para apps Node, a configuração equivalente usa baseURL.
Somente modelo: o revisor deve executar antes da publicação.
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_MODEL,
messages: [
{
role: "user",
content: "Confirme que esta solicitação de API compatível com OpenAI está sendo roteada pela Flatkey.",
},
],
});
console.log(response.choices[0].message.content);
console.log(response.usage);Este é o mesmo padrão de migração visto na documentação dos provedores: mantenha o SDK, defina uma base URL diferente, forneça uma chave de API compatível e escolha um ID de modelo que exista na plataforma de destino.
Etapa 6: Mapeie IDs de modelo de forma deliberada
A string do modelo é onde muitas migrações de API compatível com a OpenAI falham. Uma URL base pode ser compatível enquanto os IDs de modelo permanecem específicos do provedor.
Não assuma:
- Que o nome do seu modelo antigo existe na Flatkey.
- Que o alias de modelo de um provedor aponta para a mesma versão por trás de um gateway.
- Que todo modelo compatível suporta a mesma família de endpoints.
- Que um modelo que funciona para chat também funciona para visão, ferramentas, imagens, vídeo ou Responses.
Em vez disso, use esta tabela de mapeamento antes do primeiro teste no nível do app:
| Uso atual do app | Verificação na Flatkey |
|---|---|
| Chat de texto | Escolha um modelo da Flatkey que suporte o endpoint de chat da OpenAI. |
| Chat em streaming | Teste o streaming separadamente com o mesmo prompt e a mesma margem de timeout. |
| Chamada de ferramentas/funções | Verifique se o modelo e o endpoint selecionados suportam a forma de tool-call que seu app envia. |
| Saída em JSON | Teste seu response_format exato ou padrão de saída estruturada. |
| Entrada de visão/imagem | Confirme que o modelo selecionado aceita o formato de entrada de imagem que seu SDK envia. |
| API Responses | Confirme que o endpoint/modelo da Flatkey suporta /v1/responses para o seu caso de uso. |
| Geração de imagens ou vídeo | Trate isso como uma migração de endpoint separada, não como uma migração de chat completions. |
O instantâneo de preços da Flatkey em 11 de junho de 2026 mostrava famílias de endpoints para chat completions da OpenAI, OpenAI Responses, mensagens da Anthropic, Gemini, geração de imagens e vídeo da OpenAI. Isso é uma prova útil para revisores, mas o artigo ainda deve orientar os leitores a confirmar o modelo exato e o recurso que planejam usar no dia da publicação.
Passo 7: Verifique logs, cotas e faturamento
Uma resposta bem-sucedida de API compatível com OpenAI é apenas o primeiro ponto de verificação. O motivo para migrar por meio da Flatkey não é apenas a forma da requisição; é a superfície operacional em torno do acesso ao modelo.
Após o teste de fumaça, verifique:
| Área | O que inspecionar |
|---|---|
| Log de uso | A requisição aparece com timestamp, modelo, uso de tokens, status e detalhes do erro, se houver. |
| Faturamento | O custo está visível e corresponde à unidade de modelo/preço esperada. |
| Cota | Uma cota pequena pode ser definida para a nova chave ou rota de teste antes de uma implementação mais ampla. |
| Roteamento | A requisição é roteada pelo caminho pretendido da Flatkey, e não por uma configuração direta do provedor desatualizada. |
| Comportamento de erro | Erros de chave inválida, modelo inválido e parâmetro não suportado são claros o suficiente para o suporte. |
| Rollback | Restaurar a URL base/modelo anterior funciona sem mudanças no código. |
É aqui que um gateway de API compatível com OpenAI se torna mais útil do que um endpoint bruto do provedor. A alteração da URL base deve resultar em melhor visibilidade, não apenas em um upstream diferente.
Etapa 8: Faça a implantação em fases
Não mova todos os fluxos de trabalho de uma vez. Use uma implantação em etapas:
- Execute um teste de smoke direto com curl.
- Execute um teste de smoke de um SDK no ambiente local ou de staging.
- Reproduza um pequeno conjunto de prompts conhecidos e compare a estrutura da saída.
- Ative streaming ou parâmetros avançados somente depois que a chamada básica passar.
- Defina uma cota baixa para a chave de teste.
- Envie uma pequena porcentagem do tráfego não crítico.
- Compare erros, latência, uso de tokens e custo.
- Aumente o tráfego somente depois que os logs e a cobrança corresponderem às expectativas.
Esse fluxo mantém a promessa da API compatível com OpenAI ligada à realidade de produção. Compatibilidade não é um slogan; é um resultado de teste para as chamadas que seu aplicativo realmente envia.
Lista de Verificação da Migração
Use isto como o asset da página de publicação.
| Etapa | Concluído? | Notas |
|---|---|---|
| O SDK atual e o endpoint estão documentados | Python, Node, HTTP, wrapper, chat, responses, image, video, etc. | |
| A chave Flatkey foi criada | Use uma chave de teste separada, sempre que possível. | |
| A URL base está centralizada | https://router.flatkey.ai/v1 deve ficar na configuração, não espalhada pelo código. |
|
| O ID do modelo é selecionado na Flatkey | Confirme o ID do modelo do dia da publicação em preços ou no painel. | |
| O teste rápido do curl passa | O template deve ser testado pelo revisor antes da publicação. | |
| O teste rápido do SDK Python ou Node passa | Use o SDK que o seu app realmente executa. | |
| Os recursos de streaming/ferramentas/JSON/visão são testados | Teste apenas os recursos que você usa. | |
| O log de uso está visível | Confirme modelo, status, tokens e erros no painel. | |
| O faturamento e a unidade de preços são revisados | Não assuma que as unidades de preços do provedor sejam idênticas. | |
| O limite de cota está definido | Mantenha o tráfego de migração limitado. | |
| As variáveis de ambiente de rollback estão prontas | A URL base antiga e o modelo podem ser restaurados sem mudanças de código. |
Erros Comuns
O erro de migração mais comum da API compatível com OpenAI é alterar a URL base e assumir que todos os outros detalhes são idênticos. Evite estas armadilhas:
- Codificar a URL base da Flatkey em vários arquivos.
- Manter um ID de modelo antigo de um provedor que a Flatkey não roteia.
- Testar apenas sem streaming quando a produção usa streaming.
- Ignorar testes de chamadas de ferramentas ou de saída JSON.
- Migrar endpoints de imagem/vídeo como se fossem endpoints de chat-completions.
- Esquecer de atualizar tentativas, limites de timeout e análise de erros.
- Considerar a migração concluída antes de o uso e a cobrança estarem visíveis.
A Flatkey reduz a dispersão de contas de provedores e de roteamento, mas não elimina a necessidade de um teste de migração cuidadoso.
Quando o Flatkey é uma boa opção
O Flatkey é uma boa opção quando sua equipe quer uma única URL base da API compatível com OpenAI para acesso a vários modelos, em vez de contas de provedor separadas, chaves, faturamento e verificações de roteamento.
Use o Flatkey quando:
- Sua app já usa um SDK compatível com OpenAI.
- Você quer uma única chave para modelos em provedores como GPT, Claude, Gemini, DeepSeek, Qwen, Seedance 2.0 e GPT Image.
- Você quer uso, faturamento, chaves e roteamento visíveis em um único painel.
- Você quer limites de cota antes que o tráfego aumente.
- Você quer que a troca de modelos e o balanceamento de carga sejam tratados pela camada de gateway.
- Você quer que o caminho de migração seja "alterar a URL base, verificar o modelo, monitorar o uso" em vez de "recriar a integração com o modelo".
Use uma conta direta do provedor ou um proxy auto-hospedado quando você precisar de contratos específicos do provedor, lógica de roteamento totalmente personalizada ou controle de gateway local à infraestrutura.
FAQ
Uma API compatível com OpenAI é a mesma coisa que a OpenAI?
Não. Uma API compatível com OpenAI segue o padrão de requisição e resposta no estilo da OpenAI para endpoints compatíveis, mas o provedor, os IDs de modelo, a autenticação, o suporte a recursos, os preços e o comportamento de erro podem ser diferentes.
Preciso substituir meu SDK para usar a Flatkey?
Normalmente não para migrações comuns de chat completions. Se o seu SDK suportar uma URL base personalizada, muitas vezes você pode manter o SDK e alterar a configuração. Essa é a principal vantagem de uma migração para uma API compatível com OpenAI.
Qual é a URL base compatível com OpenAI da Flatkey?
Use https://router.flatkey.ai/v1 como URL base compatível com OpenAI. Para chat completions, o endpoint completo é https://router.flatkey.ai/v1/chat/completions.
Posso manter o nome do meu modelo existente?
Somente se esse ID de modelo estiver disponível e for suportado pela Flatkey. Verifique a precificação ou o painel e, em seguida, teste o ID exato do modelo antes da implementação.
Devo migrar primeiro Chat Completions ou Responses?
Migre o endpoint que seu aplicativo existente usa. Aplicativos existentes de Chat Completions podem começar com /v1/chat/completions. Se seu aplicativo usar a API Responses, teste /v1/responses separadamente e confirme que o modelo selecionado suporta os recursos de que você precisa.
Como faço para reverter?
Mantenha a URL base antiga, a chave de API e o modelo na configuração até que os logs, custos, cota e o comportamento da aplicação na Flatkey sejam verificados. A reversão deve ser uma alteração de variável de ambiente, não uma reescrita de código.
Obtenha uma chave
Se você já tem um app construído em torno de uma API compatível com a OpenAI, a Flatkey mantém a migração pequena: obtenha uma chave, altere a URL base, escolha um modelo, execute o teste de smoke e monitore o uso em um único painel.
Obtenha uma chave, depois use https://router.flatkey.ai/v1 como a URL base para o seu primeiro teste de migração da Flatkey.
