API OpenAI-compatible ou Anthropic-compatible: qual escolher?

O que API-compatible realmente significa

Uma API compatível aceita um formato de solicitação conhecido e retorna uma resposta que um SDK ou cliente existente consegue interpretar. Em uma integração comum, o desenvolvedor troca a Base URL, a API Key e o Model ID, mantendo a maior parte do código da aplicação.

O termo tem um limite claro. Um provider pode oferecer geração básica de texto sem aceitar determinado parâmetro, hosted tool, endpoint de áudio ou imagem, ou a mesma semântica de erros. Até dois endpoints que expõem o campo model podem listar modelos e conceder acesso a eles de maneiras diferentes.

Quer testar o protocolo escolhido com uma solicitação real? Você pode criar sua própria conta e API Key da BetterToken, abrir o quickstart e enviar um teste mínimo. A BetterToken oferece interfaces OpenAI-compatible e Anthropic-compatible separadas; protocolo, Base URL, tipo de API Key e Model ID atual devem corresponder à API reference atual.

Como solicitações e autenticação diferem

Em um fluxo OpenAI-compatible, o cliente normalmente cria messages para Chat Completions ou input para Responses. A autenticação costuma usar um Bearer token:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Anthropic Messages usa sua própria estrutura de mensagens, um campo system separado, um limite de output obrigatório e uma versão de protocolo. A API oficial da Anthropic usa headers como x-api-key e anthropic-version:

x-api-key: YOUR_API_KEY
anthropic-version: CURRENT_SUPPORTED_VERSION
Content-Type: application/json

Um gateway compatível pode aceitar outro esquema de autenticação. Copie os headers da documentação do endpoint que será chamado. Um exemplo da API oficial explica o formato do protocolo, mas não substitui o guia de integração do provider.

A system instruction também ocupa um lugar diferente em cada contrato. Um protocolo pode mantê-la entre as mensagens, enquanto outro a envia em um campo separado. Uma conversão mecânica pode alterar a ordem do contexto, um cache prefix ou o comportamento do cliente.

Chat Completions, Responses e Messages são contratos diferentes

A expressão OpenAI-compatible não informa qual interface foi implementada. Registre o contrato exato antes de uma migração:

• Chat Completions: um array messages, a resposta em choices e fragmentos transmitidos em delta.
• Responses API: itens de input, itens de output tipados e eventos separados do ciclo de vida da resposta.
• Anthropic Messages: messages, um campo system separado, content blocks e seus próprios eventos de stream.

Se uma biblioteca espera Responses, um endpoint que implementa apenas /chat/completions é insuficiente. Se o Claude Code espera Anthropic Messages, um endpoint OpenAI-compatible não funciona sem um adapter. Trocar somente a Base URL basta apenas quando cliente e servidor implementam o mesmo contrato.

Como streaming e conclusão diferem

As três interfaces podem transmitir dados em streaming, mas os nomes e a ordem dos eventos são diferentes.

A Responses API envia Server-Sent Events tipados para a criação da resposta, fragmentos de texto e estados finais. O cliente precisa esperar um evento de conclusão ou lidar com uma resposta failed ou incomplete.

Anthropic Messages envia message_start, eventos de content block, message_delta e message_stop. Um erro pode chegar dentro de um stream já aberto depois que a resposta HTTP inicial foi bem-sucedida.

Com Chat Completions, o cliente normalmente acumula choices[0].delta e detecta o fim de acordo com o contrato daquele endpoint. Um código que espera somente um marker não pode ser reutilizado em Responses ou Messages sem verificação.

Um handler mínimo mantém quatro estados:

created -> receiving -> completed
                   \-> failed
                   \-> disconnected

disconnected não é completed. Se a conexão terminar depois de uma resposta parcial, preserve os eventos já recebidos e decida se é seguro repetir a solicitação.

Tool use e structured output

Nomes de campos semelhantes, como tools e tool_calls, podem sugerir mais compatibilidade do que realmente existe. Teste pelo menos:

• JSON Schema e as restrições de tipos aceitas;
• tool calls paralelos;
• como o resultado de uma tool volta ao modelo;
• a montagem de argumentos recebidos por streaming;
• o comportamento diante de JSON inválido;
• strict structured output e recusas de schema.

Um adapter deve preservar o significado da chamada, não apenas renomear campos. Isso é ainda mais importante para tools com efeitos colaterais: repetir a mesma tool call pode enviar uma segunda mensagem, criar outro registro ou executar uma operação duas vezes.

Não associe erros apenas pelo status HTTP

401, 403, 404, 429 e 5xx oferecem uma primeira classificação útil, mas bodies e headers de erro variam entre providers. Preserve:

• o status HTTP;
• o tipo e o código de erro do provider;
• uma mensagem curta sem segredos;
• o request ID;
• headers relacionados a retry;
• endpoint, protocolo e Model ID.

Não registre a API Key, o prompt completo nem uma resposta sensível. Se um gateway normaliza erros, preserve o código original do provider em um campo interno seguro. Caso contrário, model not found, acesso ausente e endpoint incompatível podem acabar reduzidos a um 400 pouco útil.

Como escolher o protocolo

Uma ferramenta de IA pronta

Leia primeiro a documentação da ferramenta. Se ela pedir uma OpenAI Base URL e usar Chat Completions ou Responses, escolha o endpoint OpenAI-compatible correspondente. Se ela ler ANTHROPIC_BASE_URL e esperar Messages, use um endpoint Anthropic-compatible.

Não escolha o protocolo pelo nome do modelo. Um modelo pode estar disponível por um gateway, mas o cliente ainda exige um formato de solicitação específico.

Sua própria aplicação

A decisão depende do SDK e dos recursos que você já usa. Para uma aplicação nova, liste as capacidades necessárias: streaming, tools, structured output, vision, token usage, operações em batch ou outros endpoints. Verifique cada item na documentação oficial do provider.

Migração de provider

Avalie a superfície do contrato, não a quantidade de linhas alteradas. Um chat básico pode exigir apenas três novos valores de configuração. Uma aplicação com agents, tools, histórico longo, cache e streaming normalmente precisa de adapter e testes de integração.

Teste antes de migrar o tráfego de produção

1. Registre o SDK, o endpoint e a versão da API.
2. Copie o Model ID exato do catálogo atual.
3. Envie uma solicitação curta sem tools nem streaming.
4. Transmita uma resposta básica até seu evento terminal.
5. Execute uma tool call segura e sem efeitos externos.
6. Provoque um erro controlado com um Model ID deliberadamente inválido.
7. Compare usage, status e request ID com o Dashboard.
8. Teste o tratamento de timeout e um retry com limite de tentativas.

Só então migre o tráfego real. Com a BetterToken, comece pela API reference, escolha um protocolo e confirme uma solicitação mínima antes de habilitar agent tools.

FAQ

Uma API OpenAI-compatible reproduz completamente a OpenAI API?

Não. O termo indica compatibilidade com uma interface específica. Modelos, parâmetros, tools, streaming, erros e endpoints adicionais ainda precisam ser verificados separadamente.

Posso chamar um endpoint Anthropic-compatible com o OpenAI SDK?

Não diretamente, quando o SDK envia o contrato OpenAI. Use um cliente compatível com Anthropic Messages ou um adapter que converta corretamente mensagens, streaming e tool use.

Basta trocar a Base URL?

Às vezes, para uma solicitação curta de texto em um cliente já compatível. Em uma migração de produção, verifique também Model ID, autenticação, streaming, tools, erros e usage.

Qual protocolo o Claude Code exige?

O Claude Code normalmente usa uma interface Anthropic-compatible. Copie as variáveis, a Base URL e as configurações de modelo exatas do guia atual da BetterToken.