What "OpenAI-Compatible" Actually Buys You

When a provider says their API is OpenAI-compatible, they are making a narrow, specific promise: the request and response shapes match OpenAI's chat completions API closely enough that the official SDK works unchanged, pointed at a different address. It is an unglamorous claim about JSON field names — and it is one of the most strategically valuable sentences in enterprise AI procurement.

The reason is switching cost. The true lock-in to any vendor was never the API call; it is the rewrite, the re-evaluation, the retraining of muscle memory. When the swap is two lines of configuration, the lock-in evaporates, and with it the pricing power that lock-in protected. A compatible API converts your inference spend from a marriage into a market.

This post is the practical version of that idea: what the compatibility actually covers, what it leaves behind, and how to run a real migration test in an afternoon. We sell an OpenAI-compatible API, so read us with the same skepticism you would bring to anyone — then run the test, because the test is the point.

Migrations fail on fuzzy motives, so name yours before touching config. The three common ones demand different proofs. If you are switching for price, the thing to test is the bill on your real volumes — quality just has to clear your existing bar, not beat it. If you are switching for the catalog — access to open frontier models your current provider does not carry — the test is whether the new models actually move your product, which means evaluating them on your tasks, not admiring them on a leaderboard. If you are switching for resilience, the test is failure behavior: what a timeout looks like, what failover does to an in-flight request, how errors surface.

Write the motive at the top of the migration doc. It sounds ceremonial until week two, when someone proposes expanding the pilot to "also re-evaluate our prompting strategy" and the project quietly doubles. A migration with one success criterion finishes; a migration with five becomes a program.

The motive also decides what "done" means. A price migration is done when the same workload clears the same acceptance checks on a smaller bill. A catalog migration is done when the new capability ships. Decide now which one you are running.

Before touching anything, grep your codebase and be honest about what the integration really is. Most teams discover they use a narrow slice: chat completions, streaming, maybe tool calling and a JSON response format. That slice is exactly what compatibility covers, and for that slice the migration is an afternoon.

The inventory matters because the OpenAI surface is much larger than the slice. Assistants and threads, file uploads, provider-side batch jobs, stored fine-tunes, moderation endpoints — if your product leans on these, you are not using an API shape, you are using a hosted feature set, and no amount of endpoint compatibility moves it for you. Better to learn this from a grep than from a failed cutover.

Write the list down. It becomes both your migration scope and your rollback checklist, and it takes less time than one standup.

For the compatible slice, this is the entire migration. Python:

from openai import OpenAI

client = OpenAI( base_url="https://api.runbios.ai/v1", api_key=os.environ["RUNBIOS_API_KEY"], )

resp = client.chat.completions.create( model="glm-5.2", messages=[{"role": "user", "content": "Summarize this ticket."}], ) ```

Node looks the same — the baseURL option on the official client — and a raw curl works if you want to test without touching code:

curl https://api.runbios.ai/v1/chat/completions \
  -H "Authorization: Bearer $RUNBIOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "glm-5.2", "messages": [{"role": "user", "content": "Hello"}]}'

Change the base URL, change the key, change the model name. Everything else — streaming, tool calls, response parsing — flows through the same SDK objects you already have. The API overview covers authentication details; the model library is the menu of model ids you can put in that model field.

Across the wire, compatibility is real: message roles, streaming chunks, tool-call structures, token-usage fields. Code written against chat completions generally just works, which is the entire point.

What does not transfer is everything that lived on the provider's side of the wall. Conversations stored in their stateful features stay there. Fine-tuned models you trained on their infrastructure stay there — a sentence worth reading twice, because it is the deepest lock-in in the industry and the reason "who owns the weights" is a question to ask before fine-tuning anywhere, not after. Prompts, eval harnesses, and acceptance tests are plain text and move freely; learned artifacts often do not.

Model behavior is the other honest caveat. A compatible API does not make models interchangeable — an open frontier model and a closed flagship answer differently, phrase differently, and fail differently. Compatibility removes the engineering cost of switching. It does not remove the evaluation cost, which is what the next step is for.

Resist the urge to cut over on a good demo. Send a slice of production traffic to both endpoints in parallel — your current provider answers the user, the candidate answers a log. After a representative window, compare the shadow outputs against the acceptance checks your product already has: format validity, your quality bar, whatever you grade with.

Then cut over gradually. Route a small percentage of live traffic, watch the retry rate and the bill alongside the quality metrics, and keep the old integration alive behind a flag until the new path has seen your real peak, not just your Tuesday afternoon. Rollback should be a config value, not a deploy.

If you want the arithmetic on what the switch is worth before running any of this, the pricing calculator prices your actual volumes across models from published rates, and our price-list field guide covers how to read the rows once you have numbers to compare.

The savings get the meeting, but optionality is the durable prize. One compatible endpoint with a broad catalog means model selection becomes a config value: an open frontier model for the bulk of your traffic, a closed flagship where it earns its rate, a new model the week it ships — all behind the same key, the same SDK, the same observability.

It also changes every future negotiation. A team that can demonstrably leave in an afternoon is a team that gets called before price changes, not after. Compatibility is leverage you hold whether or not you ever pull it.

And there is a quieter operational gain: when one key and one API shape serve many models, attribution gets simpler. Per-key spend split by team and environment is much easier when there is one bill to split.

If your product is genuinely built on provider-hosted features — stateful assistants, provider-side retrieval, fine-tunes you do not own the weights to — compatibility does not move those, and pretending otherwise is how migrations stall at ninety percent. Scope the rewrite of those features honestly before starting, or decide they are worth the lock-in on purpose.

If you are mid-audit or mid-evaluation — a regulatory review, a frozen model version for reproducibility — do not introduce a migration into a process that prizes stillness. Schedule it after.

And if your inference bill is small and your roadmap is full, the honest answer is that this is not your quarter's problem. Save the playbook. Compatibility means it will still be an afternoon when the bill grows into one.