What Is an OpenAI-Compatible API?

Many AI tools ask you to configure three values:

• API key
• base_url
• model

If you have used an AI relay station, a third-party model platform, a local model gateway, or a coding agent that can point to a custom endpoint, you have probably also seen the phrase OpenAI-compatible API.

It sounds like a formal certification, but in practice it is more like an interface convention. In simple terms: a server accepts requests in a format similar to the OpenAI API, so tools that already know how to call OpenAI can call another platform with fewer changes, sometimes by changing only the URL and key.

This article explains the idea through small requests and configuration examples.

Start With a Minimal Request

Here is a typical Chat Completions style request. The domain, key, and model name are placeholders only.

curl https://relay.example.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-example",
    "messages": [
      {
        "role": "user",
        "content": "Explain OpenAI-compatible APIs in one sentence"
      }
    ]
  }'

Four parts matter:

• https://relay.example.com/v1 is the base address, often called base_url.
• /chat/completions is the specific API path, or endpoint.
• Authorization: Bearer sk-your-api-key carries the API key.
• "model": "gpt-example" chooses the model for this request.

Once these four pieces are clear, most OpenAI-compatible API configuration becomes much easier to reason about.

API Key: Who You Are and Where Usage Is Charged

An API key is the secret used to access a service. It often looks like sk-..., but the prefix is not the important part. What matters is which platform issued the key.

If you call the official OpenAI API, use a key from your OpenAI account. If you call a relay station or a third-party gateway, use the key issued by that platform. A tool does not charge OpenAI just because the environment variable is named OPENAI_API_KEY. It sends the key to whatever base_url you configured.

The common header looks like this:

Authorization: Bearer sk-your-api-key

Practical rules:

• Do not commit real keys into public repositories.
• Do not expose full keys in screenshots, articles, or logs.
• Make sure the key belongs to the same platform as the base_url.
• If the platform supports scoped keys or subaccounts, use separate keys for separate tools.

Many "my key is correct but I get 401" problems are actually key-and-URL mismatches: a key from platform A is being sent to platform B.

base_url: Where the Tool Sends Requests

base_url is the base address. It may also be called API base, endpoint base, or OpenAI base URL. It decides where the tool sends the request.

For example:

base_url = https://relay.example.com/v1

The tool then appends a concrete endpoint:

/chat/completions

The final request URL becomes:

https://relay.example.com/v1/chat/completions

This is why changing base_url lets many tools use relay providers. The tool already knows how to send OpenAI-style JSON. If you point the base URL at a relay, and the relay implements the matching OpenAI-compatible endpoint, it can receive the same kind of request.

A relay usually does several things after receiving the request:

1. Validates your API key.
2. Reads the model parameter.
3. Routes the request to the selected backend model or provider.
4. Records usage and deducts balance.
5. Returns the result in a compatible response format.

For the tool, the request format stays mostly the same. The entry point changes.

model: Which Model to Use

model is the model ID for the current request.

In the official API, it may be an official model name. In a relay station or third-party gateway, it may be the platform's own alias, or it may map to an upstream model behind the scenes.

Example:

{
  "model": "gpt-example",
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    }
  ]
}

Do not guess model names. The safest approach is to open the provider dashboard, copy the exact model ID, and use it as written.

If the model name is wrong, common results include:

• model not found
• invalid model
• a request routed to a default model
• a vague request failure in the tool

When debugging, do not look only at the key. base_url, API key, and model must all belong to the same service entry point.

Endpoint: The Specific Path After the Base URL

An endpoint is the specific API path. It describes what the request is trying to do.

Common paths include:

/v1/chat/completions
/v1/responses
/v1/models

If a tool asks for a full endpoint URL, you may need to include /v1/chat/completions. More often, a tool asks only for base_url and appends /chat/completions or /responses internally.

Read the field meaning carefully:

• base_url: often expects the address up to /v1.
• endpoint: may expect the full path.
• Responses endpoint: should point to a service that supports /v1/responses.
• OpenAI compatible URL: check the tool docs to see whether /v1 is included.

Different tools use slightly different names. Do not rely on the field name alone.

Should the /v1 Suffix Be Included?

This is one of the most common sources of confusion.

The full path of an OpenAI-style API often includes /v1, for example:

https://relay.example.com/v1/chat/completions

But whether you include /v1 in configuration depends on how the tool builds URLs.

Common patterns:

1. The tool expects base_url to include /v1, then appends /chat/completions.
2. The tool expects only the domain, then appends /v1/chat/completions.
3. The provider gives you a complete compatible base such as https://relay.example.com/v1.

Wrong configuration often creates URLs like these:

https://relay.example.com/v1/v1/chat/completions
https://relay.example.com/chat/completions

The first repeats /v1. The second misses /v1. The result is usually a 404, a missing endpoint error, or a generic request failure in the tool.

If unsure, test with a minimal request:

curl https://relay.example.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-example",
    "messages": [
      {
        "role": "user",
        "content": "hello"
      }
    ]
  }'

If that works, go back to the tool and check whether it wants https://relay.example.com or https://relay.example.com/v1.

OpenAI-Compatible Does Not Mean Everything Is Compatible

An "OpenAI-compatible API" usually means the service tries to support part of the OpenAI API convention, such as:

• HTTP JSON requests
• Bearer token authentication
• a model parameter
• messages or input for request content
• response shapes that are close enough for existing tools

It does not guarantee every feature is supported.

One platform may support only /v1/chat/completions, not /v1/responses. Another may support text chat but not images, files, tool calls, streaming, or every optional field.

So compatibility is a range, not a switch. Before configuring a tool, confirm three things:

• Does the tool use Chat Completions or Responses?
• Does the platform support that endpoint?
• What exact model names and parameters does the platform expect?

Chat Completions vs. Responses

Two endpoint families appear often in tool configuration.

Chat Completions

The path is usually:

/v1/chat/completions

The request body usually uses messages:

{
  "model": "gpt-example",
  "messages": [
    {
      "role": "user",
      "content": "Write a short title"
    }
  ]
}

This format is familiar to many chat clients, older SDK integrations, scripts, and relay platforms. The idea is direct: send a list of chat messages and ask the model to continue the conversation.

Responses

The path is usually:

/v1/responses

The request body can look like this:

curl https://relay.example.com/v1/responses \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-example",
    "input": "Write a short title"
  }'

Responses is more like a unified entry point. Some newer tools, agent frameworks, and coding assistants explicitly require Responses compatibility. If you see a config option like wire_api = "responses", the tool will call /v1/responses, not /v1/chat/completions.

The practical rule:

• If the tool uses Chat Completions, the platform must support /v1/chat/completions.
• If the tool uses Responses, the platform must support /v1/responses.
• If the platform only says "OpenAI compatible," confirm which endpoint it actually supports.

What Configuration Usually Looks Like

Many tools reduce the setup to three values:

OPENAI_API_KEY=sk-your-api-key
OPENAI_BASE_URL=https://relay.example.com/v1
OPENAI_MODEL=gpt-example

Sometimes the same idea appears as JSON:

{
  "apiKey": "sk-your-api-key",
  "baseURL": "https://relay.example.com/v1",
  "model": "gpt-example"
}

Or in a tool-specific config file:

model = "gpt-example"

[provider]
base_url = "https://relay.example.com/v1"
api_key_env = "OPENAI_API_KEY"

Field names vary, but the meaning is the same:

• the key authenticates the request
• the base URL chooses the entry point
• the model chooses the model
• the endpoint is appended by the tool or by your request

Why This Matters for Relay Stations and Multi-Model Tools

The value of OpenAI-compatible APIs is lower integration cost.

If every model platform required a different SDK, request body, and response shape, tool developers would need to build separate integrations for every provider. OpenAI-compatible APIs reuse a common convention. A tool that can send OpenAI-style requests can often connect to more platforms with only configuration changes.

For users, the practical benefits are:

• chat clients can switch model entry points
• Codex, coding assistants, and agent tools can use relay APIs
• scripts can often change environment variables instead of request logic
• one gateway or balance can sit in front of multiple models

If you are configuring Codex or Claude Code, read the more hands-on setup guide: How to Configure Codex and Claude Code with a Relay API.

If you are still choosing between a relay, the official API, and a subscription, read: AI Relay, Official API, or Subscription: Which One Should You Use?.

If token usage and billing are still unclear, start here: What Is an AI Token? A Practical Guide.

A Simple Debugging Order

When a tool cannot connect, the request fails, or the model is unavailable, check in this order:

1. Is /v1 missing or duplicated in the final URL?
2. Does the API key belong to the platform behind this base_url?
3. Is model the exact model ID from the provider dashboard?
4. Does the tool use Chat Completions or Responses?
5. Can a minimal curl request reach the platform without the tool?
6. Does the tool append paths internally, or does it expect a full endpoint?

Do not start by reinstalling the tool or switching clients. Most OpenAI-compatible API issues come back to these few values.

Summary

An OpenAI-compatible API does not mean "only OpenAI can be used," and it does not mean every platform behaves identically. It means a service provides request and response formats close enough to the OpenAI API that tools can connect through an API key, base_url, model, and supported endpoint.

The practical rule is: the key identifies you, the base URL chooses the entry point, the model chooses the model, and the endpoint chooses the capability being called.