O que compatível realmente promete
Uma API compatível com OpenAI aceita as mesmas requisições HTTP que os SDKs da OpenAI enviam. Você altera a URL base e a chave, e o cliente continua funcionando. Essa promessa está na camada de protocolo: o caminho /v1/chat/completions, um token bearer no cabeçalho Authorization, um corpo JSON com model e messages, e uma resposta com choices e usage. O streaming segue o mesmo padrão de eventos enviados pelo servidor.
Não promete o mesmo modelo, o mesmo comportamento, os mesmos limites ou o mesmo conjunto de endpoints. A empresa por trás da API original decide o que oferece, e cada outro provedor decide independentemente o que copiar. Trate a compatibilidade como uma maneira de evitar reescrever o código do cliente, não como uma garantia de que nada mais muda.
As diferenças, lado a lado
A tabela lista as áreas que variam entre provedores e o que é válido para esta API. A coluna da direita é um prompt para seus próprios testes ao avaliar qualquer serviço.
| Área | Esta API | O que verificar em qualquer provedor |
|---|---|---|
| IDs de modelo | Um id: uncensored | Se o nome do seu modelo antigo é aceito, mapeado ou rejeitado |
| Endpoints | /v1/chat/completions, /v1/responses, /v1/models | Se cada endpoint chamado pelo seu código existe |
| Modalidades | Apenas texto | Suporte a imagem, áudio e vídeo, se você precisar |
| Embeddings, fine-tuning | Não oferecido | Para onde essas chamadas serão redirecionadas |
| Janela de contexto | 100.000 tokens, prompt mais conclusão | Se o limite abrange apenas tokens de entrada ou ambos |
| Concorrência e taxa | Chave completa: 8 ao mesmo tempo, 300 por minuto. Chave de teste: 2 ao mesmo tempo, 60 por minuto | Como os limites são medidos e como uma recusa é relatada |
| Chamada de funções, modo JSON | Suportado | Casos extremos como chamadas de ferramentas em streaming |
| Comportamento de conteúdo | Ajustado para responder sem recusas de conteúdo para uso adulto legal | Camadas de moderação que alteram o que o modelo retorna |
| Faturamento | Crédito pré-pago, por token, sem subscrição | Mínimos, expiração, planos de assinatura |
A linha de preços para esta API é $0,15 por 1 milhão de tokens de entrada e $0,50 por 1 milhão de tokens de saída. Para qualquer outro serviço, leia sua página de preços atual em vez de confiar na memória ou em um resumo de terceiros.
Ids de modelo e comportamento
A maior diferença prática é o próprio modelo. Com a OpenAI você escolhe de um menu de modelos nomeados. Aqui você envia "model": "uncensored" e recebe um único modelo de pesos abertos executado por um provedor independente. Não é a API oficial de nenhum fornecedor de modelo, nem é um roteador que encaminha requisições para vários fornecedores.
Isso tem duas consequências. Primeiro, você não pode testar A/B tamanhos de modelo alterando uma string; você executa um modelo e ajusta prompts e amostragem em torno dele. Segundo, prompts escritos para outro modelo podem precisar de pequenas edições, porque o cumprimento de instruções, hábitos de formatação e comportamento de recusa diferem. Este modelo é ajustado para responder sem recusas de conteúdo para uso adulto legal, então um prompt que contém longos preâmbulos de segurança escritos para um modelo mais rigoroso pode frequentemente ser encurtado.
Um limite rígido não muda: não há conteúdo sexual envolvendo menores de idade.
Endpoints e recursos que não existem
A compatibilidade raramente é completa em toda a superfície da OpenAI. Aqui as lacunas são deliberadas: o serviço lida com texto e nada mais.
- Sem geração de imagem, áudio ou vídeo.
- Sem endpoint de embeddings, então um pipeline de recuperação precisa de um provedor de embedding separado.
- Sem fine-tuning.
O que está presente cobre a maioria dos aplicativos de chat: POST /v1/chat/completions, POST /v1/responses, streaming, chamada de ferramentas com tools e tool_choice, e modo JSON através de response_format. Controles de amostragem como temperature, top_p, stop, seed e as penalidades são repassados ao modelo.
Se o seu aplicativo mistura capacidades, o padrão usual é manter o provedor original para embeddings e imagens, e enviar apenas a geração de texto que você deseja sem censura para a nova URL base. A análise de custo e compensação considera essa divisão.
Limites, erros e cabeçalhos
Os limites são onde as migrações surpreendem as pessoas, porque eles decidem como seu código deve se comportar sob carga. Esta API define 8 requisições simultâneas e 300 requisições por minuto em uma chave completa, 2 e 60 em uma chave de teste, e um corpo máximo de 8 MB. Uma requisição que excede responde HTTP 429. O código de erro diz qual limite você atingiu: rate_limited para requisições por minuto, concurrency para muitas requisições ao mesmo tempo. Uma sobrecarga temporária também retorna 429 e adiciona Retry-After: 5.
Leia o código e o cabeçalho, não apenas o status. Retentar um erro concurrency imediatamente piora as coisas, enquanto uma espera curta resolve. Uma requisição em streaming mantém seu slot até o fim do stream, então a concorrência conta streams abertos, não apenas chamadas em andamento.
As respostas incluem X-Request-Id, X-Balance-USD, X-RateLimit-Limit-Requests e X-RateLimit-Limit-Concurrency. O cabeçalho de saldo é um extra específico do provedor: o código do SDK OpenAI o ignora, mas você pode lê-lo para rastrear gastos. O saldo também está disponível através de GET /v1/balance e do estilo OpenAI GET /v1/dashboard/billing/credit_grants.
Lista de verificação de migração
Quando você move um aplicativo entre provedores, percorra a mesma lista curta cada vez. Ela captura a maioria das surpresas antes que os usuários as vejam.
- Substitua a base URL, a chave e o id do modelo juntos, e pesquise no repositório por nomes de modelos antigos escondidos em arquivos de configuração.
- Remova chamadas para endpoints que não existem no novo lado, e redirecione-os para o provedor que os possui.
- Execute seu conjunto de prompts e compare as saídas. Espere palavras e formatação diferentes de um modelo diferente.
- Teste o streaming através de todos os proxies e balanceadores de carga entre seus usuários e a API.
- Adicione lógica de nova tentativa para 429 que lê o código de erro e o cabeçalho Retry-After.
- Registre o uso de tokens por requisição, para que surpresas de custo apareçam em dias, não no final do mês.
Um teste rápido de compatibilidade
Não confie em uma lista de recursos, incluindo esta. Execute as chamadas que seu aplicativo faz e compare os resultados. Um script curto que exercita as partes das quais você depende leva alguns minutos:
from openai import OpenAI
client = OpenAI(
base_url="https://api.apicompatible.com/v1",
api_key="YOUR_API_KEY",
)
# 1. Plain completion
r = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Reply with the word ready."}],
temperature=0,
seed=7,
)
print("plain:", r.choices[0].message.content)
# 2. JSON mode
j = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Return a JSON object with keys name and age for a fictional person."}],
response_format={"type": "json_object"},
)
print("json:", j.choices[0].message.content)
# 3. Streaming
chunks = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Count from one to five."}],
stream=True,
)
print("stream:", "".join(c.choices[0].delta.content or "" for c in chunks if c.choices))
Adicione um caso de chamada de funções se seu código usar funções, e um caso de contexto longo próximo aos tamanhos reais de prompt. Detalhes sobre cada parâmetro estão na documentação, e a página da chave de API mostra como resgatar o crédito de teste de $0,50, que é suficiente para esse tipo de verificação.
