OpenAI-Compatible vs Anthropic-Compatible APIs

What does API-compatible mean?

A compatible API takes a familiar request structure and returns a response that an existing SDK or client can parse. Typically, the developer changes the Base URL, API Key and Model ID, keeping most of the application code.

There is a limit to this formulation. The provider may support basic text generation and not support a separate parameter, built-in tool, audio, images, or the exact semantics of the error. Even two endpoints with the same field name model can form the list of available models and the rules for accessing them differently.

Want to test your chosen protocol on a real request? You can create your own BetterToken account and API Key, then open the quickstart and run one minimal test. BetterToken provides separate OpenAI-compatible and Anthropic-compatible interfaces; protocol, Base URL, API Key type and current Model ID must match the current API reference.

What is the difference between requests and authorization

In an OpenAI-compatible scenario, the client typically collects messages for Chat Completions or input for Responses API. Authorization is often passed as a Bearer token:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Anthropic Messages uses its own message structure, separate system, mandatory withdrawal limit and protocol version. The official Anthropic API contains the headers x-api-key and anthropic-version:

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

A compatible gateway may accept a different authentication method. Therefore, headers are taken from the documentation of a specific endpoint. The official API example explains the protocol format, but does not replace the provider's instructions.

The role of system instructions also differs. In one contract it is among the messages, in another it is transmitted as a separate field. Mechanical conversion may change the context order, cache prefix, or client behavior.

Chat Completions, Responses and Messages - different contracts

The word OpenAI-compatible by itself does not indicate which interface is implemented. To migrate, you need to write down the exact contract:

• Chat Completions: array messages, response via choices, streaming fragments via delta.
• Responses API: input items, typed output items and individual response lifecycle events.
• Anthropic Messages: messages, separate system, content blocks and own stream events.

If the library expects the Responses API, having only /chat/completions will not save it. If Claude Code expects Anthropic Messages, an OpenAI-compatible endpoint without an adapter will also not work. Simply replacing the Base URL only works if the client and server are implementing the same contract.

How streaming and response completion differ

All three interfaces can stream data, but the names and order of events are different.

The Responses API sends typed Server-Sent Events, such as response creation, text fragments, and terminal events. The client must wait for a completion event or process failed or incomplete.

Anthropic Messages transmits the message_start events, content block events, message_delta and message_stop. The error may appear after a successful HTTP response, inside an open stream.

In Chat Completions, the client usually accumulates choices[0].delta, and the end of the stream is determined by the contract of this endpoint. Code that looks for only one token cannot be moved to Responses or Messages without verification.

The minimal handler stores four states:

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

disconnected is not equal to completed. If the connection fails after part of the response, you need to save the received events and decide whether a repeat request is acceptable.

Tool use and structured output

The names tools and tool_calls give the impression of forward compatibility. In a production application, check at least:

• JSON Schema and restrictions on supported types;
• parallel tool calls;
• method of transferring the result of the tool back to the model;
• stream assembly of arguments;
• behavior in case of invalid JSON;
• strict structured output and refusal of the model to follow the scheme.

The adapter must preserve the meaning of the call, and not just rename the fields. This is especially important for tools with side effects: repeating the same tool call can send a message, create a record, or perform an operation a second time.

Errors cannot be matched by HTTP code alone

401, 403, 404, 429, and 5xx provide a useful first classification, but the error body and headers vary among providers. For diagnostic purposes, save:

• HTTP status;
• provider error type and code;
• a short message without secrets;
• request ID;
• retry-related headers;
• endpoint, protocol and Model ID.

Do not record the API Key, full prompt, or sensitive response. If the gateway normalizes errors, store the original provider code in a safe internal field. Otherwise, model not found, lack of access and an incompatible endpoint may turn into one uninformative 400.

How to choose a protocol

Ready-made AI tool

First, open the tool's documentation. If it asks for an OpenAI Base URL and uses Chat Completions or Responses, choose the appropriate OpenAI-compatible endpoint. If it reads ANTHROPIC_BASE_URL and expects the Messages API, it needs an Anthropic-compatible endpoint.

Do not select a protocol based on the model name. One model may be available through a specific gateway, but the client still requires a specific request format.

For example, Codex requires Responses and a valid custom provider. For the practical difference between CLI, Desktop App and Extension, see analysis of Codex CLI or Codex App and separate instructions for Codex in VS Code.

Own application

The choice depends on the SDK and features already used. When starting a new project, make a list of required features: streaming, tools, structured output, vision, token usage, batch or other endpoints. Then check them in the provider's official documentation.

Migration between providers

Evaluate the contract surface, not the number of changed lines. Basic chat may need three new configuration values. An agent application with tools, long history, caching, and streaming will often need an adapter and integration tests.

Check before migrating production traffic

1. Fix the SDK, endpoint and API version.
2. Take the exact Model ID from the current catalog.
3. Send a short request without tools and stream.
4. Check normal streaming before terminal event.
5. Perform a safe tool call without external action.
6. Create a controlled error with a deliberately incorrect Model ID.
7. Map usage, status and request ID to Dashboard.
8. Check timeout and limited retry.

Only after this do you bear the real load. For BetterToken, start with API reference, select one protocol and confirm the minimum request before connecting agent tools.

FAQ

Is the OpenAI-compatible API exactly the same as the OpenAI API?

No. The term indicates the compatibility of a particular interface. Support for models, parameters, tools, streaming, errors and additional endpoints is tested separately.

Is it possible to use an Anthropic-compatible endpoint via the OpenAI SDK?

Not directly, if the SDK generates an OpenAI contract. You need a client with support for Anthropic Messages or an adapter that correctly converts messages, stream and tool use.

Is it enough to replace the Base URL?

Sometimes - for a short text request in an already compatible client. For a production transfer, still check the Model ID, authorization, streaming, tools, errors and usage.

What protocol is needed for Claude Code?

Claude Code usually works with an Anthropic-compatible interface. Take the exact variables, Base URL and model from current BetterToken instructions.