Home → Guides → What “OpenAI-compatible” actually means

What “OpenAI-compatible” actually means

Almost every relay and self-hosted server advertises the phrase. It has a precise meaning, a hard boundary, and one failure mode that wastes an afternoon if nobody warns you about it.

The compatible part

A compatible endpoint accepts POST /v1/chat/completions with the same JSON body the OpenAI API takes — model, messages, temperature, stream, tools — and returns the same response envelope, including the choices[].message shape and server-sent events when streaming. Authentication is the same Authorization: Bearer header.

Because the shape matches, the official openai SDKs for Python and JavaScript work with nothing changed except two strings:

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_KEY",
    base_url="https://apiclan.us/v1",
)

Anything built on those SDKs inherits the compatibility. That is why Cherry Studio, Chatbox, LobeChat, LM Studio, Cursor, Cline and Roo Code all work against a compatible endpoint without any plugin: they were written against the OpenAI client and expose the base URL as a setting.

The base-URL trap

Two conventions exist and they are not interchangeable.

• OpenAI-lineage clients want the base URL to include /v1, because they append only /chat/completions.
• Anthropic-lineage clients — the Anthropic SDK, Claude Code — want the base URL without /v1, because they append /v1/messages themselves.

Get it backwards and the request goes to a path that does not exist. What comes back is a 404 from the edge, which means the request never reaches the gateway and never appears in your usage logs. From the client side it looks identical to the model not existing or the key being wrong, and you can spend an hour checking the wrong things. If a call fails and nothing shows up in your usage history at all, check the /v1 before you check anything else.

Where compatibility stops

The request shape is portable. Provider-account features are not:

• Batch endpoints, fine-tuning and file storage are account-level products, not request formats. They do not survive a relay.
• Provider-specific parameters pass through only if the upstream model accepts them. Anthropic's newest models reject non-default temperature, top_p and top_k with a 400, and reject forced tool use (tool_choice of type any or tool) because thinking is always on.
• Token accounting differs by vendor. Cache reads and cache writes are billed at different multiples of the input rate depending on the provider, so an identical conversation costs different amounts on different models even at the same headline price.

Checking an endpoint quickly

Two requests settle it. GET /v1/models tells you whether the key authenticates and what it is allowed to see. A one-token POST /v1/chat/completions tells you whether inference works. If the first succeeds and the second 404s, you have a path problem, not a permission problem.

On this platform a key belongs to exactly one group, and a group carries one family of models. A key created for text models will be refused by image models and vice versa — the fix is a second key, not a permission change. See the price list for which models sit in which group.

Start using it

No subscription, no monthly minimum, no sales call. Top up with USDT and spend what you use — 1 USDT gives you 2 credits of API balance.

Read the 30-second quickstart

Prices quoted on this page are regenerated automatically from live billing data. Third-party terms are quoted from that party's own published documentation.