OpenAI-Compatible API Guide: Change the Base URL

An OpenAI-compatible API lets an existing client keep a familiar authentication header, JSON request shape, and streaming pattern while sending traffic to a different gateway. The change can be as small as replacing the base URL and API key, but compatibility is still a protocol contract—not a promise that every model supports every endpoint or provider-specific field.

This guide explains the safe migration path for applications, scripts, and AI tools that already speak an OpenAI-style API.

What OpenAI compatibility actually covers

The most reusable parts of the contract are:

• Bearer-token authentication through the Authorization header.
• JSON requests and responses on versioned /v1 endpoints.
• Common endpoints such as /v1/models, /v1/chat/completions, and /v1/responses.
• Server-sent events for supported streaming requests.
• Familiar request fields such as model, messages, input, stream, and tool definitions when the selected protocol supports them.

Compatibility does not mean that one model can be moved freely between Chat Completions and Responses. A model may be exposed only through one verified protocol. Provider-specific reasoning, search, or multimodal fields may also require raw pass-through rather than gateway-side translation.

Treat the live Models & Pricing catalog as the source of truth for the model, group, and API format you intend to use.

Prepare the migration

Before changing application code:

1. Create a dedicated key in API Keys instead of reusing a personal or unrelated integration key.
2. Select a primary model group that can access the intended model.
3. Add ordered fallback groups only when they also support that model and fit the same cost and reliability policy.
4. Record the current endpoint, model ID, streaming setting, and tool usage so the before-and-after behavior can be compared.

The canonical Modelflare OpenAI-compatible base URL is:

https://modelflare.dev/v1

Most SDKs expect the base URL to end at /v1 and append /chat/completions or /responses themselves. Check the client's documentation before adding a second endpoint suffix.

Verify authentication and model access first

Store the key in an environment variable rather than source code:

export MODELFLARE_API_KEY='YOUR_MODELFLARE_API_KEY'

Then confirm that the key can list its available models:

curl -sS https://modelflare.dev/v1/models \
  -H "Authorization: Bearer $MODELFLARE_API_KEY"

A successful response proves that the hostname, TLS path, and key are valid. It does not yet prove that a particular request format is valid for every returned model, so the next check must use the intended endpoint.

Send one request with the intended protocol

For a Chat Completions model listed as compatible with that format:

curl -sS https://modelflare.dev/v1/chat/completions \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CHAT_MODEL",
    "messages": [
      {"role": "user", "content": "Reply with the active model name."}
    ],
    "stream": false
  }'

For a Responses-compatible coding model:

curl -sS https://modelflare.dev/v1/responses \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "Reply with the active model name.",
    "stream": false
  }'

Use the exact model ID shown in the live catalog. A model_not_found result usually means the selected key or group cannot access that model, not that changing letter case will fix the request.

Validate streaming separately

Non-streaming success is not enough for an application that depends on streaming. Repeat the request with "stream": true, confirm that events arrive incrementally, and make sure the client does not buffer the complete response before rendering it.

When diagnosing a slow stream, separate:

• time spent authenticating and selecting a route;
• time until upstream response headers;
• time until the first effective content or tool delta;
• generation throughput after visible output begins.

Modelflare usage logs retain request-level timing metadata for this purpose without storing prompts, response text, raw request bodies, API keys, emails, or plaintext IP addresses.

Production migration checklist

• Keep the API key in a secret store or environment variable.
• Pin the base URL to https://modelflare.dev/v1.
• Use a model that explicitly supports the chosen endpoint.
• Test non-streaming and streaming modes independently.
• Test tools, structured output, reasoning controls, and multimodal input if the application uses them.
• Preserve explicit zero or false values when they carry meaning in the client request.
• Set client timeouts for the real workload instead of a short health-check prompt.
• Review usage logs after cutover for status, latency, token usage, selected group, and cost.

Once the protocol boundary is verified, the client can usually keep its existing request lifecycle while Modelflare provides model access, routing policy, and per-request visibility behind the compatible endpoint.