O que é uma API compatível com OpenAI? Como funciona e onde difere

Resposta curta

Uma API compatível com OpenAI é qualquer API HTTP que aceita as mesmas requisições que a API da OpenAI e responde no mesmo formato: os mesmos caminhos (/v1/chat/completions, /v1/models e muitas vezes /v1/responses), os mesmos campos JSON e o mesmo cabeçalho Authorization: Bearer com a chave. Por isso os SDKs oficiais da OpenAI e as muitas ferramentas construídas sobre eles conseguem usá-la trocando só duas coisas: a base URL e a chave de API. «Compatível» descreve o formato das requisições, não o modelo por trás, e cada serviço suporta uma parte diferente dos recursos da OpenAI, então teste o que você usa.

Este guia é publicado pela APIVAI, um gateway compatível com OpenAI para modelos Claude e GPT. Os exemplos usam o endereço dela; os mesmos passos funcionam com qualquer serviço compatível.

O que a «compatibilidade» cobre

A maioria dos serviços copia o núcleo da API Chat Completions da OpenAI:

Parte	O que um serviço compatível aceita ou devolve
`POST /v1/chat/completions`	Um ID de modelo em `model` e um array `messages` de `{"role": ..., "content": ...}`
Resposta	`choices[0].message.content`, `finish_reason` e um objeto `usage` (`prompt_tokens`, `completion_tokens`, `total_tokens`)
Streaming	`"stream": true` devolve server-sent events, um bloco `data: {...}` por trecho de texto, terminando em `data: [DONE]`
Ferramentas	`tools` com `parameters` em JSON Schema; o modelo responde com `tool_calls` e você devolve os resultados como mensagens `role: "tool"`
`GET /v1/models`	A lista de IDs de modelo que sua chave pode usar
Autenticação	`Authorization: Bearer <chave>`
Erros	JSON no formato `{"error": {"message": ..., "type": ..., "code": ...}}`

Serviços mais novos também implementam POST /v1/responses, a API Responses mais recente da OpenAI, que algumas ferramentas (o Codex CLI, por exemplo) usam no lugar do Chat Completions. Menos serviços oferecem /v1/embeddings ou endpoints de imagem, áudio ou arquivos.

Onde os serviços diferem: checklist

A compatibilidade nunca é completa. Antes de mover tráfego real, verifique:

IDs de modelo. Cada serviço nomeia os modelos do seu jeito. Leia-os de GET /v1/models em vez de reaproveitar os nomes da OpenAI.
Parâmetros ignorados. Campos não suportados costumam ser descartados sem erro: response_format, seed, logprobs, n > 1, presence_penalty e a flag strict das ferramentas. A requisição «funciona», mas faz menos do que você pensa.
Faixas de parâmetros. Alguns modelos rejeitam valores que a OpenAI aceita (por exemplo, temperature acima de 1, ou definir temperature e top_p ao mesmo tempo).
Endpoints além do chat. Embeddings, imagens, áudio, arquivos, batch e fine-tuning muitas vezes não existem.
Uso no streaming. A contagem de tokens em respostas em streaming pode exigir "stream_options": {"include_usage": true} ou nem ser enviada.
Erros e limites. O JSON de erro costuma ter o formato certo, mas códigos de status, mensagens e cabeçalhos de limite (x-ratelimit-*, retry-after) variam.
Ferramentas e imagens. A maioria dos modelos grandes suporta, mas teste chamadas em paralelo, tool_choice forçado e imagens no modelo exato que você vai usar.

Quem oferece uma API compatível com OpenAI

Alguns exemplos bem documentados:

Serviço	Base URL	Observações
Ollama (local)	`http://localhost:11434/v1`	Chat Completions, Completions, modelos, embeddings e um endpoint Responses sem estado; a chave é obrigatória, mas ignorada
vLLM (auto-hospedado)	`http://localhost:8000/v1`	Iniciado com `vllm serve <modelo>`; serve Chat Completions, Completions, Responses, embeddings e modelos
LM Studio (local)	`http://localhost:1234/v1`	Modelos, Chat Completions, Completions, Responses e embeddings
Anthropic	`https://api.anthropic.com/v1/`	A Anthropic a descreve como uma camada para testar e comparar modelos, não como caminho de produção de longo prazo; cache de prompts e alguns campos só existem na API nativa
Google Gemini	`https://generativelanguage.googleapis.com/v1beta/openai/`	Em beta, segundo o Google
Gateways de API	A URL do próprio gateway	Colocam modelos de vários provedores atrás de uma chave e um formato; a APIVAI é um deles, para Claude e GPT (veja também APIVAI vs. OpenRouter)

Repare nas base URLs: a maioria termina em /v1, a do Gemini não. Sempre copie a base URL da documentação do provedor.

Como trocar um app para outro serviço compatível

Os SDKs oficiais da OpenAI leem duas variáveis de ambiente, então muitos apps trocam sem mudar o código:

export OPENAI_BASE_URL="https://api.apivai.com/v1"
export OPENAI_API_KEY="your-key"

Ou defina no código. Python:

from openai import OpenAI

client = OpenAI(base_url="https://api.apivai.com/v1", api_key="your-key")
resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
print(resp.choices[0].message.content)

Node.js:

import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.apivai.com/v1", apiKey: "your-key" });
const resp = await client.chat.completions.create({
  model: "gpt-6-luna",
  messages: [{ role: "user", content: "Say hello in one sentence." }],
});
console.log(resp.choices[0].message.content);

Teste com curl antes de mexer no app:

curl https://api.apivai.com/v1/models -H "Authorization: Bearer your-key"

A regra do /v1. Os SDKs acrescentam /chat/completions à base URL, então a base URL já precisa conter a versão (.../v1). Um 404 quase sempre significa que o /v1 está faltando ou repetido. Cada ferramenta acrescenta algo diferente, então siga o guia da sua.

Ferramentas que aceitam uma URL compatível com OpenAI

A maioria das ferramentas de IA para programar e conversar tem uma opção «custom OpenAI-compatible» ou «OpenAI base URL». Guias passo a passo:

Agentes e editores de código: Cline, Roo Code, Kilo Code, Continue, Cursor, Zed, Aider, OpenCode, Goose, Open Interpreter e Codex CLI (no guia do Claude Code)
Apps de chat: Cherry Studio, Chatbox, LobeChat, Open WebUI
Automação: Dify, n8n

Chamando o Claude no formato da OpenAI

A API própria do Claude usa outro formato (/v1/messages, x-api-key, um campo system no nível superior). Para usar o Claude a partir de uma ferramenta no formato OpenAI, é preciso algo que traduza: a camada de compatibilidade da própria Anthropic (acima) ou um gateway como a APIVAI, que aceita requisições no formato OpenAI com IDs de modelos Claude em https://api.apivai.com/v1. Ferramentas que falam o formato da Anthropic nativamente, como o Claude Code, podem usar https://api.apivai.com diretamente; veja o guia do Claude Code e a documentação da API.

Perguntas frequentes

«Compatível com OpenAI» quer dizer que todos os recursos da OpenAI funcionam?

Não. Quer dizer que o formato básico de requisições e respostas coincide. Cada serviço suporta uma parte: chat e streaming quase sempre, ferramentas e imagens na maioria dos modelos grandes, e embeddings, áudio, arquivos e batch com bem menos frequência. Campos não suportados costumam ser ignorados em silêncio, então teste os recursos de que você depende.

Preciso mudar meu código?

Normalmente só a base URL, a chave e o ID do modelo. Se o seu código usa recursos exclusivos da OpenAI (por exemplo, saídas estruturadas com response_format ou a Assistants API), verifique se o novo serviço os suporta.

O mesmo código consegue falar com um modelo local?

Sim. Ollama, vLLM e LM Studio rodam um servidor compatível com OpenAI, então o mesmo código do SDK funciona com base_url em http://localhost:11434/v1, http://localhost:8000/v1 ou http://localhost:1234/v1. IDs de modelo e recursos suportados mudam conforme o servidor e o modelo.

A base URL termina em /v1?

Na maioria dos serviços, sim: o SDK acrescenta /chat/completions, então a base URL precisa terminar na versão. Alguns provedores usam outro caminho (o do Gemini termina em /v1beta/openai/), então copie da documentação deles.

Como descubro quais modelos um serviço suporta?

Chame GET /v1/models com sua chave; os IDs da resposta são os que vão em model. Preços e tamanhos de contexto ficam na página de preços do provedor; para a APIVAI, na página de modelos.