What "OpenAI-Compatible" Actually Buys You

When a provider says the 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. An unglamorous claim about JSON field names — and 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 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. An OpenAI-compatible API is sold here, so read with the same skepticism brought to anyone — then run the test, because the test is the point.

Migrations fail on fuzzy motives — name yours before touching config. The three common ones demand different proofs. Switching for price: the thing to test is the bill on real volumes — quality just has to clear the existing bar, not beat it. Switching for the catalog — access to open frontier models the current provider does not carry: the test is whether the new models actually move the product, meaning evaluation on your tasks, not admiration on a leaderboard. Switching for resilience: the test is failure behaviour — 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 is being run.

Before touching anything, grep the 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 — a product leaning on these is not using an API shape, it is using a hosted feature set, and no amount of endpoint compatibility moves it. Better to learn this from a grep than from a failed cutover.

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

For the compatible slice, that is the whole migration, start to finish. Python:

from openai import OpenAI

client = OpenAI( base_url="https://api.vidman.ai/v1", api_key=os.environ["VIDMAN_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 for testing without touching code:

curl https://api.vidman.ai/v1/chat/completions \
  -H "Authorization: Bearer $VIDMAN_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 already in hand. The API overview covers authentication details; the model library is the menu of model ids for that model field.

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

What does not transfer is everything living on the provider’s side of the wall. Conversations stored in their stateful features stay there. Fine-tuned models 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 behaviour 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, 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 cutting over on a good demo. Send a slice of production traffic to both endpoints in parallel — the current provider answers the user, the candidate answers a log. After a representative window, compare the shadow outputs against the acceptance checks the product already has: format validity, the quality bar, whatever is graded 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 the real peak, not just Tuesday afternoon. Rollback should be a config value, not a deploy.

For the arithmetic on what the switch is worth before running any of this: the pricing calculator prices actual volumes across models from published rates, and the price-list field guide covers reading the rows once there are numbers to compare.

The savings win the meeting; 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 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 held whether or not it is ever pulled.

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

A product genuinely built on provider-hosted features — stateful assistants, provider-side retrieval, fine-tunes whose weights are not owned — cannot be moved by compatibility, 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.

Mid-audit or mid-evaluation — a regulatory review, a frozen model version for reproducibility — is the wrong moment to introduce a migration into a process that prizes stillness. Schedule it after.

And a small inference bill with a full roadmap: the honest answer is that this is not the quarter’s problem. Save the playbook — compatibility means it will still be an afternoon when the bill grows into one.