Guide · Developer migration

What does OpenAI-compatible API mean?

An OpenAI-compatible API accepts the request and response conventions used by the OpenAI SDKs, so an application can change its base URL and key without rewriting the integration layer. OpenLux supports the chat, image, embedding and model-listing paths used by most compatible clients, but compatibility still needs a protocol test for your exact workload.

OpenAI SDKBase URLMigrationAPI compatibility

Reviewed by OpenLux Engineering Team · Last verified 2026-11-03

Create an API key Read the docs

Abstract orange glass sculpture illustrating OpenAI-compatible API on OpenLux — OpenAI-compatible API + OpenLux — one key, one endpoint, one bill.

Which OpenLux endpoints can compatible clients call?

The public documentation describes these paths. Confirm model-specific behaviour before relying on an advanced parameter.

Endpoint	Typical use	Compatibility note
/v1/chat/completions	Chat, reasoning, agents, tool calling and multimodal input	Use the OpenAI SDK with base_url https://openlux.lol/v1 and a catalogue model name
/v1/images/generations	Text-to-image generation and image workflows	Model names and request units vary; check the image model page and live catalogue
/v1/embeddings	Vector embeddings for search and retrieval	Use an embedding model in the retrieval category and store the returned vectors
/v1/models	Discover the models exposed by the compatible endpoint	Use the live response as the source of truth; the marketing catalogue can include availability status

How we evaluated this

This guide was reviewed against the public OpenLux docs and the compatibility behaviour that OpenAI SDKs depend on on 3 November 2026: base URL, authentication headers, request shape, response shape, streaming and standard HTTP errors. It does not claim compatibility with every optional OpenAI parameter or every beta surface.

Run a representative test suite against the exact model and endpoint before switching production traffic. Model-specific features can evolve faster than the generic compatibility contract.

OpenAI-compatible migration checklist

A two-line change is the happy path. These checks make sure the rest of the contract is still intact.

Set base_url to https://openlux.lol/v1 and keep the API key in the server-side secret store.
Map each existing model name to an OpenLux catalogue name and record the dependency.
Verify a normal non-streaming completion and one malformed request.
Verify streaming, final finish reason and cancelled requests.
Verify tool/function calls, JSON arguments and a follow-up tool result.
Verify multimodal input only on a model that explicitly supports it.
Check the error shape for 401, 402, 429 and 5xx responses in your retry layer.
Compare request logs, latency and usage cost before moving the default route.

Set it up in four steps

Create a server-side key

Sign in to the OpenLux console, create a scoped API key and store it in your secret manager. Do not expose it in a browser or commit it to Git.

Change the base URL and key

Point the OpenAI SDK at https://openlux.lol/v1 and select a catalogue model. Keep environment-specific values outside the application code.

Run the compatibility suite

Test normal, streamed, tool, multimodal, invalid-key and rate-limit paths. Compare the results with your current provider.

Move traffic gradually

Route a non-critical queue or percentage first. Watch logs, latency, quality and cost before changing the default.

What is an OpenAI-compatible API?

The OpenAI-compatible label describes an HTTP interface that follows the conventions of the OpenAI API closely enough that an OpenAI SDK or compatible client can point at a different base URL. Authentication still uses a bearer token, requests use familiar JSON fields and responses return a choices array or the equivalent shape for the endpoint.

Compatibility is a spectrum rather than a certification. A provider may match chat completions while differing on image parameters, beta features or optional headers. The reliable test is your own SDK path and request set, not a logo on a comparison page.

Is an OpenAI-compatible API server the same as a hosted gateway?

An OpenAI-compatible API server can be an application or proxy running in your own environment, such as a local model server exposing chat completions. A hosted gateway exposes the same familiar contract as a managed service. Both can share a request shape while differing in ownership, authentication, data path and the models behind the endpoint.

OpenLux is a hosted gateway, not software you deploy. Your application sends an OpenAI-style request to https://openlux.lol/v1, and OpenLux authenticates the key, selects the requested catalogue model, records usage and returns the response.

How do you migrate an existing OpenAI SDK integration?

The first change is the client configuration. In Python, set base_url to https://openlux.lol/v1 and pass the OpenLux key. The rest of the OpenAI client call stays familiar. In JavaScript, use the same baseURL option supported by the official SDK.

The second change is the model identifier. Replace the provider-specific model string with a name from the OpenLux catalogue, such as gpt-6-astra, claude-sonnet-4-5-20250929 or gemini-3.8-flash. Keep model names in configuration rather than scattered through the application.

Which endpoints and request shapes are supported?

The OpenLux docs publish /v1/chat/completions, /v1/images/generations, /v1/embeddings and /v1/models. Chat supports streamed responses, tool calling and multimodal input on models that accept those features. The catalogue identifies the model family and unit price.

Do not assume every optional parameter from every OpenAI API version is accepted. Test response format, seed, reasoning controls, image editing and other advanced fields against the model you plan to use. If a parameter is not documented, treat it as unsupported until verified.

How do you list the models available on an OpenAI-compatible API?

Call GET /v1/models with the same bearer key used for chat requests. The response lists the model identifiers exposed by the endpoint. Use that live response for client configuration, then check the OpenLux model catalogue for current modalities, capabilities and published rates.

The model list confirms availability, not quality or feature parity. A model can appear in the list while lacking tools, vision or a specific optional parameter. Keep a separate compatibility test for the paths your application calls.

Which clients and frameworks work with an OpenAI-compatible endpoint?

The official OpenAI Python and Node SDKs are the baseline. Compatible clients include Vercel AI SDK, LangChain and many coding agents that accept a custom base URL. OpenLux publishes step-by-step guides for Codex, Claude Code, Cursor, OpenCode, Roo Code, Kilo Code and Vercel AI SDK because each tool exposes configuration in a different place.

For a client not covered by a guide, look for an OpenAI provider type, custom base URL or compatible endpoint field. Set the base URL to https://openlux.lol/v1, provide a server-side key and use an exact catalogue model ID.

How should streaming be tested?

A streaming request should open promptly, emit incremental chunks and terminate with a clear finish reason. Test a normal response, an upstream timeout and a client-side cancellation. Your application needs to release resources after cancellation even if the gateway or provider continues for a short time.

Measure time to first token separately from total completion time. A gateway can be fast overall but slow to first byte, which is still a poor experience for interactive products. Record both metrics for the incumbent and the new endpoint.

What changes with tool calling?

Tool calling depends on the model returning structured function names and arguments that your application can parse. Test the complete loop: initial tool request, validation of arguments, execution of the local function, submission of the tool result and final assistant response.

Different models can be more or less reliable at choosing tools and producing valid JSON. A protocol-level success is not a task-level success. Keep a small evaluation set for tool selection, argument validity and recovery after an invalid call.

How does multimodal input work?

Vision-capable chat models accept image inputs as part of the message payload. The model must be selected explicitly; a compatible endpoint does not make every model multimodal. Image size, supported formats and token accounting can vary by model.

Test representative images at the dimensions and file sizes your product uses. If your application depends on image understanding, include a quality check as well as a 200 response; the model can accept the image and still return an unhelpful answer.

How should errors and retries work?

The documented error classes are 401 for an invalid or disabled key, 402 for insufficient balance, 429 for rate limits and 5xx for upstream or routing failures. Your retry policy should distinguish authentication and billing errors from transient failures; retrying a bad key only wastes time.

Use exponential backoff with jitter for rate limits and transient server failures. Cap retries, make requests idempotent where possible and log the request ID or traceable metadata your provider exposes. Keep customer content out of logs that do not need it.

What does OpenAI compatibility not guarantee?

It does not guarantee identical model quality, identical tokenisation, identical context limits or identical latency. It also does not guarantee that every provider-specific parameter, beta endpoint or multimodal feature will behave the same way.

The compatibility contract gives you a familiar integration path. Your product still needs an evaluation set, a fallback policy and a model-specific acceptance test. This is especially important when a catalogue offers models from several vendors with different training and safety behaviour.

What should you monitor after migration?

Monitor request success, latency percentiles, time to first token, token usage, cost per request and fallback frequency. Keep the model name and gateway version in your own telemetry so a regression can be traced to a routing or model change.

Review the first week of real traffic with product and engineering. A migration is complete when the new endpoint meets the same quality and reliability bar, not when the demo request returns 200.

Minimal migration examples

The request shape stays familiar. Only the base URL, key and model identifier change.

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    base_url="https://openlux.lol/v1",
    api_key="sk-openlux-...",
)

response = client.chat.completions.create(
    model="gpt-5.6-sol",
    messages=[{"role": "user", "content": "Summarise this support ticket."}],
)
print(response.choices[0].message.content)

Node.js (OpenAI SDK)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://openlux.lol/v1",
  apiKey: process.env.OPENLUX_API_KEY,
});

const response = await client.chat.completions.create({
  model: "gemini-3.8-flash",
  messages: [{ role: "user", content: "Explain this error." }],
});

cURL

curl https://openlux.lol/v1/chat/completions \
  -H "Authorization: Bearer $OPENLUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "messages": [{"role":"user","content":"Hello"}]
  }'

Good first models for a migration test

Model	Vendor	Price	Vs. official
gpt-5.6-sol	OpenAI	$0.1838 / 1M tokens	-96%
gemini-3.8-flash	Google	$0.0551 / 1M tokens	-92%
claude-sonnet-4-5-20250929	Anthropic	$0.2647 / 1M tokens	-91%
deepseek-v4	DeepSeek	$0.0613 / 1M tokens	-90%

Prices are metered in USD; the full list lives in the model catalogue.

Key takeaways

OpenAI-compatible means the client contract is familiar, not that every model or parameter is identical.
Change base_url, key and model name first, then test the protocol paths your application uses.
Streaming, tools, multimodal input, error handling and retries need separate acceptance tests.
Keep model names in configuration and log them so a model change can be diagnosed.
Move traffic gradually and compare quality, latency and cost before the final cutover.

Frequently asked questions

Can I use the official OpenAI Python and Node SDKs?

Yes. Set the SDK base URL to https://openlux.lol/v1 and use an OpenLux key. Test the exact endpoints and optional parameters your application uses.

Do I need to change my API request body?

For standard chat completions, the request shape is familiar. The model field must change to a catalogue model name. Advanced or provider-specific parameters should be verified before production.

Does OpenLux support streaming?

The chat completions endpoint supports streamed responses. Test time to first token, chunk handling, finish reason and cancellation behavior for your SDK version.

Does OpenLux support tool calling and vision?

Chat completions supports tool calling and multimodal input on models that accept those features. Use the model catalogue and docs to confirm support for the specific model.

What error codes should I handle?

Handle 401 for authentication, 402 for insufficient balance, 429 for rate limits and 5xx for transient upstream or routing failures. Retry only errors that are safe and likely to recover.

Is every OpenAI endpoint available?

The public docs list chat completions, image generations, embeddings and models. Treat undocumented endpoints or parameters as unsupported until verified with the OpenLux team.

How do I list models through the compatible API?

Call GET /v1/models with an OpenLux bearer key. Use the returned IDs for client configuration and the public catalogue for capabilities, modalities and current rates.

Does an OpenAI-compatible endpoint work with Vercel AI SDK?

Yes. Vercel AI SDK can use @ai-sdk/openai-compatible and createOpenAICompatible with the OpenLux base URL and key. Test the model-specific streaming and tool behaviour your application requires.

Sources and official documentation

OpenLux API docsOfficial quickstart, endpoints and error codes.
OpenLux model catalogueModel identifiers, modalities and rates.
OpenAI API referenceReference for the SDK conventions the compatible endpoint follows.
Codex integration guideA concrete client configuration example.
Claude Code integration guideBridge-based integration example.

Test compatibility with your own SDK

Create a key, run the migration checklist and keep the old endpoint available until your quality and latency tests pass.

Create an API key See pricing