What Is an OpenAI-Compatible API? Endpoints, SDK Setup, and Provider Switching

An OpenAI-compatible API implements enough of OpenAI's HTTP and SDK conventions that an existing client can call it without a complete integration rewrite. For a standard chat application, the portable core is usually the /v1/chat/completions request and response shape: change the base URL, API key, and model ID, then keep using client.chat.completions.create().

The word compatible does not mean identical. A provider may support Chat Completions but not Responses, embeddings, audio, or every parameter. Model behavior, tool calling, streaming events, errors, rate limits, and token accounting can also differ. Treat compatibility as an endpoint-by-endpoint contract that you verify against your own workload.

What OpenAI-compatible means in practice #

Most compatible chat APIs preserve four conventions:

1. A versioned base URL, commonly ending in /v1.
2. Bearer-token authentication through the Authorization header.
3. A POST /v1/chat/completions route with a model and messages array.
4. A response whose generated message is available under choices[0].message.

That common surface is why the official OpenAI SDKs can work with services operated by other companies. The Python client exposes a base_url option; the JavaScript client uses baseURL. Many IDEs, coding agents, workflow tools, and self-hosted model servers expose the same setting under a label such as OpenAI Compatible, API Base, or Custom Provider.

Compatibility is a convention, not a certification program. Always check which route the client sends and which route the provider implements.

Common endpoints and RouterPlex support #

An OpenAI-compatible service does not need to implement the entire OpenAI API. Start with the endpoint your application actually calls.

RouterPlex currently exposes 38 models across 14 providers: 37 chat models plus one image model. It does not automatically choose a model for a request. Your application sends an exact model ID from the live model catalog.

Call an OpenAI-compatible API with curl #

A direct HTTP request makes the compatibility boundary easy to see:

curl https://api.routerplex.com/v1/chat/completions \
  -H "Authorization: Bearer $ROUTERPLEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {
        "role": "user",
        "content": "Explain what an API gateway does in two sentences."
      }
    ]
  }'

The base URL is https://api.routerplex.com/v1. When configuring an SDK, give it that base URL and let the SDK append /chat/completions. Do not put the full endpoint into a setting that expects only the base URL.

To inspect the model IDs available to the key:

curl https://api.routerplex.com/v1/models \
  -H "Authorization: Bearer $ROUTERPLEX_API_KEY"

Use an exact returned id as the model value. Display names and IDs from another provider are not guaranteed to work.

Python SDK setup #

Install the official client:

pip install openai
export ROUTERPLEX_API_KEY="sk-..."

Then configure base_url:

import os
from openai import OpenAI
 
client = OpenAI(
    api_key=os.environ["ROUTERPLEX_API_KEY"],
    base_url="https://api.routerplex.com/v1",
)
 
response = client.chat.completions.create(
    model="claude-opus-4-8",
    messages=[
        {
            "role": "user",
            "content": "Give me three checks for a safe database migration.",
        }
    ],
)
 
print(response.choices[0].message.content)

The SDK class and method stay the same. The provider-specific values are the credential, base URL, model ID, and any optional parameters supported by that model.

JavaScript and TypeScript SDK setup #

Install the same official package used for OpenAI:

npm install openai
export ROUTERPLEX_API_KEY="sk-..."

Configure baseURL with a capital URL:

import OpenAI from "openai";
 
const client = new OpenAI({
  apiKey: process.env.ROUTERPLEX_API_KEY,
  baseURL: "https://api.routerplex.com/v1",
});
 
const response = await client.chat.completions.create({
  model: "gemini-3.5-flash",
  messages: [
    {
      role: "user",
      content: "Summarize this release note in one sentence.",
    },
  ],
});
 
console.log(response.choices[0].message.content);

Keep API keys in a server-side environment variable. The JavaScript SDK blocks browser use by default because shipping a long-lived API credential to a browser would expose it to users.

A provider-switching configuration that stays portable #

Do not scatter provider URLs and model IDs across the application. Put the three values that normally change behind environment variables:

import os
from openai import OpenAI
 
client = OpenAI(
    api_key=os.environ["AI_API_KEY"],
    base_url=os.environ["AI_BASE_URL"],
)
 
response = client.chat.completions.create(
    model=os.environ["AI_MODEL"],
    messages=[{"role": "user", "content": "Return only the word ready."}],
)

For a RouterPlex test, set:

export AI_API_KEY="$ROUTERPLEX_API_KEY"
export AI_BASE_URL="https://api.routerplex.com/v1"
export AI_MODEL="gpt-5.5"

This makes a basic provider comparison a configuration change, but it does not remove the need for testing. Model IDs are provider-specific, and optional features may require code changes.

What compatibility does not guarantee #

The safest assumption is: the common request can be portable while the operational contract is not.

Migration checklist #

1. Inventory every API method the application calls, including background jobs and fallback paths.
2. Move the base URL, API key, and model ID into configuration.
3. Map each old model ID to an exact model ID supported by the new provider.
4. Replay a small golden set for plain chat, streaming, tools, structured output, and vision where applicable.
5. Validate the response shape before reading optional fields.
6. Test authentication failures, unknown models, rate limits, timeouts, and insufficient credit.
7. Compare token counts, latency, output quality, and billed cost on the same inputs.
8. Add a canary or feature flag so traffic can return to the previous route quickly.
9. Give the test integration its own key and hard budget before running agentic or high-concurrency work.

Within RouterPlex, switching among GPT, Claude, Gemini, DeepSeek, Kimi, Qwen, and other supported models usually changes only the model string because they share the Chat Completions route. You still need to test model-dependent tools, vision, structured output, context limits, and output behavior.

Verification and troubleshooting #

A 404 response

Check whether the client expects a base URL or a full endpoint. For the OpenAI Python and JavaScript SDKs, use https://api.routerplex.com/v1; the SDK appends the method path. A client that specifically requires the Responses API must use a provider route that implements /v1/responses.

A 401 authentication error

Confirm the key belongs to the provider at the configured base URL. Make sure the environment variable is available to the actual process, container, or serverless function making the request.

A model-not-found error

List models from /v1/models or copy the ID from the RouterPlex catalog. Do not assume an alias from OpenAI or another gateway exists.

An unsupported-parameter error

Reduce the request to model and messages, confirm the basic route, then add optional fields back one at a time. Check the selected model's capabilities before enabling tools, vision, or structured output.

Streaming works differently

Inspect the raw server-sent events and make the consumer tolerant of optional fields. Test the terminal event, partial tool calls, empty deltas, and interrupted streams rather than checking only visible text.

The request succeeds but quality changes

API compatibility does not make models interchangeable. Evaluate correctness, format adherence, tool selection, latency, and total cost on representative tasks before moving production traffic.

Run a bounded compatibility test #

RouterPlex gives one API key and one prepaid balance for 38 models across 14 providers. Create a dedicated key, set a hard lifetime budget, and run the same small evaluation through two or three model IDs. That verifies the SDK route, the model behavior, and the billed cost without exposing the full account balance.

Start with a $5 RouterPlex account, follow the quickstart, or compare the wider LLM gateway landscape.