Migrating to an OpenAI-Compatible API: a Practical Guide

#ai #api #openai #tutorial

Originally published on boostrail.com on August 5, 2026.

"OpenAI-compatible" is the most load-bearing phrase in AI infrastructure, and it means something concrete: a service that accepts the same requests and returns the same responses as OpenAI's API — same endpoints, same JSON shapes, same streaming format. Your existing OpenAI SDK code works against it after changing exactly one thing: the base URL.

That's why the OpenAI format has become the industry's common protocol, the way S3's API became the standard for object storage. This guide walks through what a migration actually involves — which is less than you'd think — and the few places where checking first saves a surprise later.

The one-line migration

Both official OpenAI SDKs accept a base_url (Python) / baseURL (JavaScript) parameter. Point it at a compatible endpoint, swap the key, and everything else stays:

# Python — before and after
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_BOOSTRAIL_KEY",
    base_url="https://api.boostrail.com/v1"   # the only new line
)

response = client.chat.completions.create(
    model="claude-sonnet-5",   # any model in the catalog
    messages=[{"role": "user", "content": "Hello"}]
)

// JavaScript / TypeScript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_BOOSTRAIL_KEY",
  baseURL: "https://api.boostrail.com/v1",
});

const response = await client.chat.completions.create({
  model: "claude-sonnet-5",
  messages: [{ role: "user", content: "Hello" }],
});

No new SDK, no new dependency, no request-shape changes. The same works for any framework that exposes a base-URL setting — LangChain, LlamaIndex, Vercel AI SDK and most others do.

What carries over unchanged

The point of compatibility is that the boring majority of your integration just works:

Chat completions — client.chat.completions.create with the full messages array semantics
Streaming — server-sent events arrive in the same chunk format, so existing stream parsers keep working
Tool calling — tools, tool_calls, content parts and streaming tool-call deltas work in the same format
Model listing — /v1/models returns the catalog, so model pickers keep working

One endpoint difference worth knowing about: an API can also expose other clients' native protocols alongside the OpenAI surface. On BoostRail, Anthropic-protocol clients like Claude Code talk to /v1/messages and Codex CLI talks to /v1/responses — each client uses the protocol it was built for, with no local adapter. Details are on the OpenAI-compatible API page.

What to check before you flip the switch

Compatibility covers the protocol; a few behaviors legitimately differ per model and are worth a look:

Model names. gpt-4o-era strings won't name the same model everywhere. Check the catalog and pick explicitly — switching later is a one-string change.
Parameter ranges. Temperature runs 0–2 in the OpenAI convention but 0–1 on Anthropic's API. BoostRail passes the value on as you send it rather than rescaling it, so if your product exposes a temperature slider, check its range against the models you call.
Token limits. Different models have different context windows and default output caps. If you hard-coded max_tokens for one model, confirm it fits the new one.
Prompt behavior. A prompt tuned hard against one model may need a round of adjustment on another. Migrate the plumbing first, then A/B the prompts — don't change both at once.

Migrating coding agents

Coding agents migrate the same way, usually via environment variables rather than code:

// Claude Code — ~/.claude/settings.json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.boostrail.com",
    "ANTHROPIC_API_KEY": "YOUR_API_KEY",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
  }
}

Cline, OpenCode, Continue and Aider take a standard OpenAI-compatible provider block. Per-tool walkthroughs live on the coding tools page, and the rate-limit reasons agents benefit most from this migration are covered in Coding Agents and Rate Walls.

Rollback is also one line

The migration is symmetric: point base_url back at the provider's official endpoint and you've left. No proprietary SDK and no export process.

FAQ

Will responses be byte-identical to OpenAI's?
The JSON structure is identical; the content depends on which model you call. Field-level extras (like provider-specific metadata) may appear but won't break standard parsers.

Do I need to migrate everything at once?
No. Because both sides speak the same protocol, you can run a percentage of traffic through the new endpoint, compare, and cut over gradually.

What about my fine-tuned or provider-specific models?
Models that exist only in your own provider account, such as fine-tunes, are not in the catalog, so BoostRail can't serve them — keep calling those on the provider's own endpoint. If you have contract prices for catalog models, BYOK runs them on your own provider keys; see the BYOK guide.

DEV Community