夜雨聆风调用大模型 API，URL 里总带着这些东西：
/v1/chat/completions
/v1/messages
/v1/responses
/v1/embeddings
/v1/models
/v1beta/models/{model}:generateContent很多开发者把它们当路径名，换个 base_url 就完事了。但这些后缀其实是不同的接口协议，规定了你怎么发请求、怎么收响应、错误怎么报、流式怎么收。同一模型可以走不同协议，同一协议可以被不同厂商支持，兼容程度各不相同。
下面按协议逐个拆解。
/v1 不是模型版本
/v1管的是接口规范，不是模型能力。
常见的误解：/v1 = 第一代模型，/v2 = 第二代。实际上 /v1 约束的是请求字段叫什么、响应字段叫什么、错误格式是什么、流式事件怎么发、工具调用怎么表达、鉴权方式是什么。模型版本是 gpt-5.5、claude-sonnet-4-8 这样的独立概念。
厂商通常不会在同一个稳定 API 版本下修改核心结构。要改就新开 /v2，或者新增一套接口（比如 /v1/responses），否则存量应用全得崩。
/v1/completions：已经淘汰的文本续写
早期大模型是补全模式，给一段文字，接着往下写：
POST /v1/completions
{
"model": "chatgpt",
"prompt": "Translate this into Chinese: Hello"
}模型没有角色概念，不区分谁是用户、谁是助手。想做对话得自己拼字符串：
System: You are a helpful assistant.
User: Hello.
Assistant: Hi, how can I help?
User: Explain API suffixes.
Assistant:问题在于：模型得从文本里猜各部分的角色归属，多模态输入和工具调用也没法结构化表达。这个接口已经被更结构化的协议取代了。
/v1/chat/completions：目前兼容性最好的协议
过去几年的事实标准。OpenAI、Mistral、xAI、DeepSeek、Groq、OpenRouter 都支持。
POST /v1/chat/completions
{
"model": "gpt-5.5",
"messages": [
{ "role": "system", "content": "You are a concise technical explainer." },
{ "role": "user", "content": "Explain /v1/chat/completions." }
]
}核心变化是 messages 数组。每条消息带 role（system / user / assistant / tool），上下文从一坨字符串变成了有结构的消息对象。
切换厂商时通常只改三样：
base_url
api_key
model业务代码基本不用动。
"兼容 OpenAI" 不等于全部兼容。
基础部分（model、messages、temperature、stream）大多没问题，但高级功能各家支持程度不同：
Level 1：文本聊天
Level 2：流式输出
Level 3：工具调用
Level 4：结构化输出
Level 5：多模态输入
Level 6：复杂 agent 事件流接入前确认目标厂商支持到哪一层。
/v1/messages：Claude 的消息协议
Anthropic 走了自己的路。接口路径是 /v1/messages，细节差别不小。
两个最明显的差异：
system 位置不同。 OpenAI 把 system 放在 messages 数组里当一个 role，Claude 把它提到顶层当独立参数：
{
"system": "You are helpful.",
"messages": [{ "role": "user", "content": "Hello." }]
}响应结构不同。 OpenAI 的文本在 choices[0].message.content，Claude 在 content[0].text。Claude 的 content 是 block 结构，文本、图片、工具调用各自是不同类型的 block。
两者不能直接通用，需要做协议转换。
/v1/responses：OpenAI 的新接口
/v1/chat/completions 名字里带着 chat 和 completions 两个历史包袱。设计初衷是"给聊天历史，补全下一条回复"。但当前模型要做的事远不止聊天：搜网页、读文件、调函数、跑代码、处理图片音频，全往里塞的话结构越来越拧巴。
Responses API 把输入输出都抽象化了：
POST /v1/responses
{
"model": "gpt-5.5",
"input": [
{
"role": "user",
"content": [{ "type": "input_text", "text": "Search and summarize." }]
}
],
"tools": [{ "type": "web_search" }]
}输出不再是一条 assistant message，而是包含多个 output item 的 response object，可以承载文本、工具调用和中间结果。
简单聊天场景继续用 /v1/chat/completions 没问题，生态兼容性最好。做 agent 相关的东西，Responses API 值得优先看看。
models/{model}:generateContent：Google 的风格
POST /v1beta/models/{model}:generateContent这是 Google API 的标准写法：对某个模型资源执行某个方法。/v1beta 是预览版（可能变化），/v1 是稳定版。
数据结构也不同：
OpenAI: messages -> role + content
Anthropic: messages -> role + content blocks
Gemini: contents -> role + parts三家三种写法，解析代码各写各的。
/v1/embeddings：文本向量化
POST /v1/embeddings
{
"model": "text-embedding-3-large",
"input": "AI API suffixes"
}返回一组浮点数向量。语义搜索、RAG 检索、相似度匹配、聚类、推荐都靠它。
RAG 的典型流程：embeddings 把文档切片转成向量存入向量库，用户提问时问题也转成向量检索相似片段，片段塞进聊天接口生成答案。Embeddings 负责找资料，聊天接口负责写答案。
/v1/models：模型列表
GET /v1/models
GET /v1/models/{model}返回可用模型列表、模型 ID 和消耗信息。调试 404 model_not_found 时第一个查的就是它。
响应结构对比
三家的返回格式不同，解析代码不能混用：
OpenAI Chat Completions:
text = response.choices[0].message.content
Anthropic Messages:
text = response.content[0].text
OpenAI Responses:
text = response.output_text流式输出格式也不统一。OpenAI 用 data: {"choices":[{"delta":...}]} + data: [DONE]，Claude 用 event: message_start / content_block_delta / message_stop 事件流，Responses API 也有自己的事件类型。
/openai、/api 前缀是什么
第三方平台为了兼容 OpenAI SDK，在路径里加了自己的命名空间：
https://api.groq.com/openai/v1/chat/completions
https://openrouter.ai/api/v1/chat/completions
https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions/openai、/api 表示"这里提供兼容 OpenAI 协议的入口"。开发者继续用 OpenAI SDK，改个 base_url 就行。
Base URL 和 Endpoint 的坑
填 Base URL 时填到 /v1 就停：
✅ https://api.openai.com/v1
✅ https://openrouter.ai/api/v1别填完整路径。SDK 会自动拼 /chat/completions，填多了就变成：
❌ /v1/chat/completions/chat/completions → 404填 Endpoint / Full URL 时才需要完整路径。
工具调用
普通聊天只需输出文本，agent 场景需要模型调工具。三家的表达方式各不相同：
Chat Completions: tools / tool_calls / tool role
Claude Messages: 工具调用作为 content block
Responses API: 工具调用作为 response output item做复杂 agent 需要考虑：并行调用、流式调用、服务端状态、内置工具、MCP、结构化输出、错误恢复。这些各家差异不小。
怎么选
普通聊天 → /v1/chat/completions
agent + 现代能力 → /v1/responses
接 Claude → /v1/messages
接 Gemini → /v1/models/{m}:generateContent
做 RAG → /embeddings + 任一聊天接口
接第三方平台 → 先确认它兼容哪种协议厂商路径速查
OpenAI /v1/chat/completions 传统聊天
OpenAI /v1/responses 新一代 agent
OpenAI /v1/embeddings 向量化
Anthropic /v1/messages Claude 原生
Google /v1/models/{m}:generateContent Gemini 稳定
Mistral /v1/chat/completions OpenAI 风格
xAI /v1/chat/completions OpenAI 风格
DeepSeek /chat/completions 兼容 OpenAI
Groq /openai/v1/chat/completions 高速推理
OpenRouter /api/v1/chat/completions 多模型聚合
