OpenAI-compatible API migration checklist

Inventory the contract you use

List endpoints, model aliases, request options, streaming events, response fields, error handling, and usage metadata consumed by your code. Search the application for assumptions about provider-specific headers, finish reasons, image response formats, and tool-call serialization.

Run a compatibility matrix

1. Authentication: verify header format and key scoping.
2. Happy path: compare parsed responses, not just HTTP 200.
3. Streaming: confirm event order, termination, and interrupted connections.
4. Errors: test invalid model, invalid input, rate limit, and timeout cases.
5. Accounting: capture usage fields and reconcile them with provider records.

Keep rollback cheap

Put the base URL, credential, model mapping, timeout, and retry policy in configuration. Avoid scattering provider checks through business logic. During rollout, keep the previous route available and move a small percentage of traffic first.

client = OpenAI(
    api_key=os.environ["AI_API_KEY"],
    base_url=os.environ["AI_API_BASE_URL"],
    timeout=30,
)

Use a repeatable checker

The provider compatibility guide and migration checker provide fixtures you can adapt to your own routes.