You want your application to use AI. You open the docs and run into a pile of terms: endpoint, protocol, Chat Completions API, Responses API, Messages API, and compatible everywhere you look.
They sound like things at the same level, but they aren’t. The cost of mixing them up is concrete: you can spend ages staring at a 404, or get a 400 and assume the model doesn’t support what you asked for.
I’ll use sending a parcel as an analogy to sort out the three terms.
The one-minute version
| Term | Parcel analogy | What it is | What an error looks like |
|---|---|---|---|
| Endpoint | Delivery address | A URL path | 404 Not Found |
| Protocol | Envelope and form layout | The request body’s JSON structure | 400 Invalid field |
| API | The entire delivery service | Both of the above together | —— |
In one sentence: send it to the wrong address and it can’t be delivered (404); use the right address but fill out the form incorrectly and the recipient can’t understand it (400).
Why they get mixed up
Most of the time, one protocol is attached to one fixed address, so the two seem inseparable. You copy a code sample from the docs, bringing over both the address and the format, and never need to think about them independently.
They come apart only when you encounter cases like these:
- You change providers, so the address changes but the format doesn’t (OpenAI-compatible)
- One provider offers two addresses and supports two formats (dual stack)
- A provider introduces a new format while keeping the old address around (generations)
Let’s take them one by one.
OpenAI has two generations of protocols; Anthropic has one
This is where assumptions tend to creep in. It’s easy to imagine the two providers have matching structures. They don’t.
OpenAI: the old one is still here, and the new one has arrived
| Protocol | Endpoint | Status |
|---|---|---|
| Chat Completions | /v1/chat/completions |
Established; the de facto industry standard |
| Responses | /v1/responses |
New generation |
Chat Completions arrived early and got copied widely. The entire ecosystem grew around its shape. Keep that in mind when we get to “compatibility.”
Anthropic: everything goes through one endpoint
Anthropic has only the Messages API, with a single endpoint:
POST /v1/messages
Tool use, structured output, extended thinking, prompt caching: all of these are parameters on that one endpoint, not separate APIs.
So the question “What’s the difference between Anthropic’s Responses API and Chat API?” starts from a false premise: Anthropic doesn’t have those generations. To change capabilities, change the parameters, not the address.
What “OpenAI-compatible” means
Many providers’ docs say “this API is OpenAI-compatible.” They mean:
My address is my own, but the envelope format follows OpenAI’s exactly. Replace the URL and key in your existing code with mine; you shouldn’t have to change anything else.
That’s a typical case of a protocol separating from its endpoint:
协议：OpenAI Chat Completions（照抄）
端点：https://我自己的域名/v1/chat/completions（自己的）
Why does everyone copy OpenAI’s format? It arrived first and gained many users. Copying it lets a provider accept existing code and SDKs from across the ecosystem. That’s ecosystem inertia, not evidence that the format is technically better.
A real example: one key, two addresses, two formats
MiniMax, an upstream provider, offers both:
| Which style | Endpoint | Protocol |
|---|---|---|
| Anthropic style | /v1/messages |
Anthropic Messages |
| OpenAI style | /v1/chat/completions |
OpenAI Chat Completions |
The same account and the same key work with either style. That demonstrates that the protocol and endpoint are distinct: otherwise, one provider couldn’t support both.
In practice: one field chooses the route
In our API gateway, each upstream provider declares which “dialect” it speaks:
- name: museav
api_mode: chat_completions # 说 OpenAI 方言
base_url: https://manager.museav.top/api
- name: minimax-anthropic
api_mode: anthropic_messages # 说 Anthropic 方言
base_url: https://api.minimaxi.com/anthropic
api_mode has three possible values, corresponding to the three protocols above:
api_mode |
Protocol | Endpoint |
|---|---|---|
chat_completions |
OpenAI Chat Completions | /v1/chat/completions |
anthropic_messages |
Anthropic Messages | /v1/messages |
codex_responses |
OpenAI Responses | /v1/responses |
What happens if you declare the wrong one? The address works, but the request body’s shape doesn’t match. The server can’t understand the request and returns a 400 complaining about an invalid field.
The nastiest error: an extra version in the URL
I’ve run into this twice in practice. Both times it produced a 404; both times it took a while to diagnose.
Code typically builds the URL like this:
最终地址 = 服务商给的 base_url + 固定路径
The fixed path is /v1/chat/completions. The problem is that some providers include a version in their base_url:
| Provider’s base_url | Constructed URL | Result |
|---|---|---|
https://api.deepseek.com |
.../v1/chat/completions |
✅ Works |
https://xxx.com/v1 |
.../v1/ v1 /chat/completions |
❌ 404 |
https://open.bigmodel.cn/api/paas/v4 |
.../v4/ v1 /chat/completions |
❌ 404 |
Why it’s hard to spot: the key is right, the model name is right, and the protocol is right. The configuration table looks fine, yet every request fails. No automatic check catches it, either: concatenation happens in code, and the configuration table doesn’t show the resulting URL.
The first time, a provider’s base ended in /v1, and I fixed only the /v1 case. The second time, Zhipu’s base ended in /v4. The same trap caught me again in a slightly different form.
Three nested layers
Putting it together, from top to bottom:
协议（JSON 长什么形状）
messages 怎么组织、tools 怎么声明、流式事件什么结构
↓ 挂载在
端点（URL 路径）
/v1/chat/completions · /v1/messages · /v1/responses
↓ 拼接靠
base_url + path
这一步拼错 = 404，且配置全对也救不了
A troubleshooting rule of thumb
| Symptom | Check this layer first | Typical cause |
|---|---|---|
| 404 Not Found | Endpoint | URL assembled incorrectly; missing or extra version |
| 400 Invalid parameter | Protocol | Wrong protocol; field names don’t match |
| 401 / 403 | Neither | Key missing, expired, or lacking permission |
| Request succeeds but response is empty | Neither | Response format or model capability |
First decide whether the shape or the address is wrong. That tells you where to look. The investigation takes a completely different path in each case; guessing wrong can cost half a day.
Recap
- An endpoint is the address, a protocol is the envelope format, and an API refers to both together. For a 404, check the address; for a 400, check the format.
- OpenAI has two generations of protocols (Chat Completions and Responses); Anthropic has one (Messages), with capabilities expressed as parameters.
- “OpenAI-compatible” means using OpenAI’s envelope format at your own address. That’s a product of ecosystem inertia.
- One provider can support two protocols at once. That’s proof that protocol and endpoint can come apart.
- Watch for versions already present in the base URL when assembling the address. One extra
/v1produces a 404 even though all the configuration looks right.
