Guides · 2026-08-05 · 3 min read

Migrating to an OpenAI-Compatible API: a Practical Guide

"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 pass through intact
• Model listing — /v1/models returns the catalog, so model pickers keep working

One endpoint difference worth knowing about: a gateway can also expose *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 — no lossy translation in the middle. 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 models; a compatible gateway handles the mapping, but if your product exposes a temperature slider, its range assumption is worth revisiting.
• 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"
  }
}

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, no export process, no data held hostage. That symmetry is worth requiring from any infrastructure you adopt — the easier a service is to leave, the less it needs lock-in to keep you.

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 exclusive to one provider account can be reached via BYOK — your own provider keys used through the gateway — so they sit behind the same endpoint as everything else. How that works is covered in the BYOK guide.