深度解析 AI API 里的 `v1/messages`、`v1/chat/completions`、`v1/responses`：这些后缀到底是什么，为什么要这样设计？

2- /v1/chat/completions

/v1/chat/completions 是过去几年最重要、最广泛兼容的 LLM API 协议。

接口和请求如下：

POST /v1/chat/completions

{
  "model": "gpt-5.5",
  "messages": [
    {
      "role": "system",
      "content": "You are a concise technical explainer."
    },
    {
      "role": "user",
      "content": "Explain what /v1/chat/completions means."
    }
  ]
}

这时接口从一个整体的 prompt 输入变成了一个可以结构化进行处理的消息数组。

2.1- messages 是 Chat Completions 的核心

messages 通常包含这些角色：

system      系统指令，定义模型行为边界
user        用户输入
assistant   模型之前的回复
tool        工具调用结果

**这让对话变得结构化。**也避免了我们需要手动提示 AI 下面这些内容：

User:
Assistant:
System:

我们可以把每条消息作为对象传进去。上下文从字符串变成了一组具有角色和顺序的一串消息组。

2.2- 兼容 /v1/chat/completions

/v1/chat/completions 算是一种行业上通用的协议。

OpenAI:       /v1/chat/completions
Mistral:      /v1/chat/completions
xAI:          /v1/chat/completions
DeepSeek:     /chat/completions 或 OpenAI 兼容路径
Groq:         /openai/v1/chat/completions
OpenRouter:   /api/v1/chat/completions
Together AI:  /v1/chat/completions

由于这个基础设施已经很完善了，不管是 SDK 还是 AI 的各种 IDE，前端的一些聊天软件还有一些 RAG 框架都支持了这个 OpenAI 的 Chat Completions，所以我们如果直接用这个基础设施的话，我们只需要改 Base URL、API key 和模型就好了，也就是下面这些：

base_url
api_key
model

例如原来调用 OpenAI：

from openai import OpenAI

client = OpenAI(
    api_key="OPENAI_API_KEY",
    base_url="https://api.openai.com/v1"
)

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[
        {"role": "user", "content": "Hello"}
    ]
)

切换到某个 OpenAI-compatible 服务时，常常只需要改成：

client = OpenAI(
    api_key="OTHER_PROVIDER_API_KEY",
    base_url="https://api.other-provider.com/v1"
)

但是这里的兼容并不意味着完全的兼容。只是在一些方面，用户可以比较轻松地使用而已。

2.3- OpenAI-compatible 的兼容程度有层级

[!INFO] OpenAI-compatible 的兼容层级
兼容 OpenAI API，通常至少意味着它支持：

POST /v1/chat/completions

model、messages

temperature

max_tokens 或 max_completion_tokens

stream

choices[0].message.content

但不一定完整支持：

tools、tool_choice、parallel_tool_calls

response_format、JSON schema strict mode

vision input、audio input/output

logprobs、reasoning tokens、cached tokens

streaming tool-call delta、structured outputs

所以兼容可以分层理解：

Level 1：普通文本聊天兼容
Level 2：支持流式输出
Level 3：支持函数调用 / 工具调用
Level 4：支持结构化输出
Level 5：支持多模态输入
Level 6：支持复杂 agent 事件流和状态管理

官方资源：

OpenAI Chat Completions：

2.4- Chat

Mistral Chat API：

docs.mistral.ai

2.5- Chat

Welcome to Mistral AI’s Api Reference

xAI Chat Completions：

docs.x.ai

2.6- Chat | Inference API - REST API Reference | xAI Docs

Chat and Responses API endpoints

DeepSeek Chat Completion：

api-docs.deepseek.com

2.7- Create Chat Completion | DeepSeek API Docs

Creates a model response for the given chat conversation.

Groq OpenAI Compatibility：

GroqDocs

2.8- OpenAI Compatibility - GroqDocs

Learn how to use OpenAI’s client libraries with Groq API, including configuration, supported features, and limitations.

OpenRouter Chat Completion：

openrouter.ai

2.9- Create a chat completion | OpenRouter | Documentation

Sends a request for a model response for the given chat conversation. Supports both streaming and non-streaming modes.

3- /v1/messages，Claude 的消息协议

Anthropic Claude 的核心接口是下面这个。各个模型厂商都希望推出自己的一些协议，让别人来兼容它。说的就是你 A

POST /v1/messages

{
  "model": "claude-sonnet-4-8",
  "max_tokens": 1024,
  "system": "You are a careful technical explainer.",
  "messages": [
    {
      "role": "user",
      "content": "Explain /v1/messages."
    }
  ]
}

看起来像，但是不是一个东西。

3.1- Claude 的 `system` 通常是顶层字段

OpenAI Chat Completions 常见写法：

{
  "messages": [
    {
      "role": "system",
      "content": "You are helpful."
    },
    {
      "role": "user",
      "content": "Hello."
    }
  ]
}

Anthropic Messages 常见写法：

{
  "system": "You are helpful.",
  "messages": [
    {
      "role": "user",
      "content": "Hello."
    }
  ]
}

Claude 把系统指令作为顶层参数，而 OpenAI 则是将其设为了普通消息数组中的一个 role。

3.2- Claude 的 content 更强调 block 结构

**Claude Messages API 的内容可以是字符串，也可以是 content blocks。**例如文本、图片、工具调用结果等都可以作为不同 block 表达。

[!NOTE] 响应结构差异对比
OpenAI Chat Completions 常见解析路径：
choices[0].message.content
Claude Messages 常见解析路径：
content[0].text
响应里还会有 type、role、content、stop_reason、usage.input_tokens、usage.output_tokens。

所以 OpenAI 和 Claude 的接口不能通用，我们必须想一个办法把它进行转换一下才可以。

官方资源：

Anthropic Messages API：

Claude API Reference

3.3- Messages - Claude API Reference

API reference for Messages endpoints

Anthropic Messages 使用指南：

3.4- Using the Messages API

Practical patterns and examples for using the Messages API effectively

Anthropic Streaming Messages：

4- /v1/responses，统一响应对象

OpenAI 的 /v1/responses 则给出了更现代化的统一接口。

从

POST /v1/responses

{
  "model": "gpt-5.5",
  "input": "Explain why /v1/responses exists."
}

转变为更结构化的请求：

{
  "model": "gpt-5.5",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Search the web and summarize the result."
        }
      ]
    }
  ],
  "tools": [
    {
      "type": "web_search"
    }
  ]
}

4.1- 为什么需要 Responses API

/v1/chat/completions 的名字里有两个历史词：chat 和 completions。

作为原来的开发者，他们认为用户给一段聊天历史，然后 AI 来补全下一条信息。但是现在的模型并不仅仅只是聊天了，它还有更多、更复杂的事情需要做：

读取图片、处理音频、查询文件、搜索网页、调用函数
使用代码解释器、调用 MCP 工具、维护服务端上下文
输出结构化 JSON、返回推理摘要、产生多个中间事件

如果我们把这些能力全部塞进 chat.completion 这个对象，会越来越别扭。

OpenAI 在 Responses API 中设计了一套更通用的数据结构，用于包含各种文本工具调用、工具返回的结果以及一些状态信息等，让这个内容更加抽象和宽广。

4.2- Chat Completions 与 Responses 的核心差异

[!NOTE] 核心模式对比

Chat Completions 更像：

用户：这是聊天记录

模型：这是下一条回复

Responses 更像：

用户：这是任务、上下文和可用工具

模型：这是我执行后的完整响应，包括文本、工具调用和中间结果

这更适合 Agent 场景。

4.3- 为什么新项目更应该关注 /v1/responses

如果只是做简单聊天，/v1/chat/completions 仍然非常实用，因为生态兼容性最好。

但如果涉及以下能力：

工具调用、网页搜索、文件搜索、代码解释器
多模态输入、复杂流式事件、服务端状态、agent workflow

那么更应该优先研究 Responses API。

官方资源：

OpenAI Responses API：

4.4- Responses

OpenAI Chat Completions 与 Responses 迁移指南：

4.5- Migrate to the Responses API | OpenAI API

5- Google Gemini models/{model}:generateContent

Gemini 的 REST API 路径经常长这样：

POST /v1beta/models/{model}:generateContent

或者：

POST /v1/models/{model}:generateContent

这和 OpenAI、Anthropic 的命名风格明显不同。

拆开看：

/v1beta
API 版本

/models/{model}
模型资源

:generateContent
对这个模型资源执行 generateContent 方法

这里反映的是对某个模型的资源执行内容的生成方法，而不是访问某一个服务。

5.1- v1 和 v1beta 的区别

文档明确区分：

v1       稳定 API 版本
v1beta   Beta / 预览能力，可能变化

5.2- Gemini 的数据结构也不同

Gemini 通常使用 contents、parts 这类结构，而不是 OpenAI 风格的 messages。

概念上可以理解为：

OpenAI Chat Completions:
messages -> role + content

Anthropic Messages:
messages -> role + content blocks

Gemini:
contents -> role + parts

官方资源：

Gemini API Versions：

5.3- API 版本说明 | Gemini API | Google AI for Developers

Gemini Generate Content API：

5.4- Generating content | Gemini API | Google AI for Developers

Gemini API 文档首页：

5.5- Gemini API | Google AI for Developers

Gemini API 文档和 API 参考文档

6- /v1/embeddings 向量接口

/v1/embeddings 经常和聊天 API 一起出现：

POST /v1/embeddings

{
  "model": "text-embedding-3-large",
  "input": "AI API suffixes explained"
}

这个会将文本生成一组浮点数向量进行返回。

{
  "data": [
    {
      "embedding": [0.0123, -0.0456, 0.0789]
    }
  ]
}

**Embedding 的作用是把文本变成向量。**它常用于：

语义搜索、RAG 检索、相似度匹配、聚类、推荐、去重、分类

例如做 RAG 时，典型流程是：

1. 用 /v1/embeddings 把文档切片转成向量
2. 存入向量数据库
3. 用户提问时，把问题也转成向量
4. 检索最相似的文档片段
5. 把片段塞进 /v1/chat/completions 或 /v1/responses 生成答案

embeddings 负责找资料。

官方资源：

OpenAI Embeddings Guide：

6.1- Vector embeddings | OpenAI API

Learn how to turn text into numbers, unlocking use cases like search, clustering, and more with OpenAI API embeddings.

OpenAI Embeddings API Reference：

7- /v1/models 模型列表

/v1/models 通常用于列出可用模型或查询模型详情。

GET /v1/models
GET /v1/models/{model}

这个就很简单，它告诉调用的软件或者程序有哪些模型，哪个模型是不是存在，模型的 ID 是什么，还有它的一些消耗是怎么样的。

列出账号可用模型
检查模型名称是否正确
动态展示模型选择列表
调试 404 model_not_found 问题

官方资源：

OpenAI Models API：

8- 为什么一定要有 /v1

很多人会误以为：

/v1 = 第一代模型
/v2 = 第二代模型

这是错的。

[!IMPORTANT] 核心澄清：/v1 是 API 版本，而不是模型版本

API 版本约束的是：

请求字段、响应字段、错误格式、流式事件表达、工具调用、鉴权方式、文件上传格式等。

模型版本（如 gpt-5.5、claude-sonnet-4-8）约束的是：

模型能力、模型大小、上下文长度、推理能力、价格和速度。

API 的版本只是为了让后面的新规范兼容前面的规范，而不破坏之前的应用使用。

{
  "choices": [
    {
      "message": {
        "content": "Hello"
      }
    }
  ]
}

如果明天厂商直接改成：

{
  "output": [
    {
      "content": [
        {
          "text": "Hello"
        }
      ]
    }
  ]
}

就会出问题。

所以厂商通常不会随便改变同一个稳定 API 版本的核心结构。要么新开一个版本，比如 /v2，要么新增一套接口，比如 /v1/responses。

9- /openai、/api、/compatible-mode

很多第三方平台不是 OpenAI，但为了兼容 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、/compatible-mode、/api 通常是平台自己的命名空间。

它们表达的是：

这不是 OpenAI 官方服务
但这里提供一套接近 OpenAI 协议的兼容入口

例如 Groq 的 base URL 是：

https://api.groq.com/openai/v1

OpenRouter 的 chat completions 路径是：

https://openrouter.ai/api/v1/chat/completions

这类平台一般希望开发者继续使用 OpenAI SDK：

from openai import OpenAI

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key="OPENROUTER_API_KEY"
)

然后再调用：

client.chat.completions.create(...)

SDK 内部会把 /chat/completions 拼到 base URL 后面。

10- Base URL 和 Endpoint

10.1- 如果软件让你填 Base URL

[!WARNING] Base URL 的填写规范（SDK 自动拼接）
配置 Base URL 时，通常应当填到 /v1 为止：

https://api.openai.com/v1

https://api.groq.com/openai/v1

https://openrouter.ai/api/v1

不要填完整的 https://api.openai.com/v1/chat/completions！因为绝大多数 SDK 会在内部自动拼接 /chat/completions。如果填了完整路径，实际请求会因为双后缀（如 /v1/chat/completions/chat/completions）而报 404 错误。

10.2- 如果软件让你填 Endpoint / Full URL

那就需要填完整路径：

https://api.openai.com/v1/chat/completions

10.3- 判断配置项的经验规则

Base URL / API Base / OpenAI Base URL:
填到 /v1，一般不要带 /chat/completions。

Endpoint / Full URL / Request URL:
填完整路径。

Provider:
选择协议类型，例如 OpenAI、Anthropic、Gemini。

Model:
填模型 ID，不要填 URL。

11- 不同接口的响应结构不同，解析代码不能混用

11.1- OpenAI Chat Completions 常见响应

{
  "id": "chatcmpl_xxx",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 5,
    "total_tokens": 15
  }
}

常见解析路径：

text = response.choices[0].message.content

11.2- Anthropic Messages 常见响应

{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello"
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 10,
    "output_tokens": 5
  }
}

常见解析路径：

text = response.content[0].text

11.3- OpenAI Responses 常见响应

{
  "id": "resp_xxx",
  "object": "response",
  "output": [
    {
      "type": "message",
      "content": [
        {
          "type": "output_text",
          "text": "Hello"
        }
      ]
    }
  ]
}

常见解析路径取决于 SDK，可能是：

text = response.output_text

或者手动遍历：

for item in response.output:
    ...

12- 流式输出也不是统一格式

很多接口都支持：

{
  "stream": true
}

但流式事件格式并不相同。

OpenAI Chat Completions 通常是：

data: {"choices":[{"delta":{"content":"Hel"}}]}
data: {"choices":[{"delta":{"content":"lo"}}]}
data: [DONE]

Anthropic Messages 可能是：

event: message_start
event: content_block_start
event: content_block_delta
event: content_block_stop
event: message_stop

Responses API 也有自己的事件类型。

13- 工具调用

普通聊天只需要输出文本，但 agent 应用需要模型调用工具。

例如用户问：

查一下今天武汉天气，再帮我决定要不要带伞。

模型可能要：

1. 判断需要天气工具
2. 生成 tool call
3. 工具返回天气数据
4. 模型读取工具结果
5. 生成最终建议

在 Chat Completions 里，工具调用通常通过 tools、tool_calls、tool role 表达。

在 Claude Messages 里，工具使用是 content block 的一部分。

在 Responses API 里，工具调用和工具结果更像 response item / output item 的一部分，更适合复杂事件流。

[!NOTE] 构建复杂 Agent 时的考量维度

工具调用格式

是否支持并行工具调用

是否支持流式工具调用

是否支持服务端状态

是否支持内置工具

是否支持 MCP

是否支持结构化输出

是否支持错误恢复

14- 主流 AI 厂商接口路径对照表

厂商 / 平台	常见接口路径	协议风格	主要用途
OpenAI	`/v1/responses`	OpenAI 新一代统一响应协议	文本、多模态、工具、Agent、新项目优先关注
OpenAI	`/v1/chat/completions`	OpenAI Chat Completions	传统聊天、兼容生态、普通对话
OpenAI	`/v1/embeddings`	Embeddings	文本向量化、RAG、搜索
OpenAI	`/v1/models`	Models	查询模型列表
Anthropic Claude	`/v1/messages`	Anthropic Messages	Claude 原生对话、工具、多模态
Google Gemini	`/v1/models/{model}:generateContent`	Google generateContent	Gemini 稳定接口
Google Gemini	`/v1beta/models/{model}:generateContent`	Google beta generateContent	Gemini 预览能力
Mistral	`/v1/chat/completions`	OpenAI-like Chat Completions	聊天、工具调用、结构化输出
xAI	`/v1/chat/completions`	OpenAI-like Chat Completions	Grok 文本 / 图像理解聊天
DeepSeek	`/chat/completions` 或兼容 OpenAI 路径	OpenAI-like Chat Completions	DeepSeek 对话模型
Groq	`/openai/v1/chat/completions`	OpenAI-compatible	高速推理，复用 OpenAI SDK
OpenRouter	`/api/v1/chat/completions`	OpenAI-compatible aggregator	多模型聚合路由

15- 如何选择该用哪个接口

可以按场景判断。

15.1- 只是普通聊天

优先选：

/v1/chat/completions

原因是生态最成熟，SDK、代理、网关、前端工具兼容最好。

15.2- 新项目接 OpenAI，并且需要现代能力

优先研究：

/v1/responses

尤其是涉及：

工具调用、文件搜索、网页搜索、多模态、结构化输出、agent workflow、服务端状态

15.3- 接 Claude 官方能力

用：

/v1/messages

不要强行把 Claude 当成 OpenAI Chat Completions。

15.4- 接 Gemini

用：

/v1/models/{model}:generateContent

或者根据需要使用：

/v1beta/models/{model}:generateContent

稳定项目优先 v1，实验功能再考虑 v1beta。

15.5- 做 RAG / 向量搜索

需要组合：

/v1/embeddings
+
/v1/chat/completions 或 /v1/responses 或 /v1/messages

Embedding 负责检索，聊天接口负责生成答案。

15.6- 接第三方聚合服务

先确认它兼容哪种协议：

OpenAI-compatible、Anthropic-compatible、Gemini-compatible

然后再选择对应 SDK 和路径。

16- 具体官方资源链接整理

16.1- OpenAI

OpenAI Responses API：

16.2- Responses

OpenAI Chat Completions API：

16.3- Chat

OpenAI Chat Completions / Responses 迁移指南：

16.4- Migrate to the Responses API | OpenAI API

OpenAI Embeddings Guide：

16.5- Vector embeddings | OpenAI API

Learn how to turn text into numbers, unlocking use cases like search, clustering, and more with OpenAI API embeddings.

OpenAI Embeddings API：

16.8- Anthropic Claude

Anthropic Messages API：

Claude API Reference

16.9- Messages - Claude API Reference

API reference for Messages endpoints

Anthropic Messages 使用指南：

16.10- Using the Messages API

Practical patterns and examples for using the Messages API effectively

Anthropic Streaming Messages：

16.12- Google Gemini

Gemini API 版本说明：

16.13- API 版本说明 | Gemini API | Google AI for Developers

Gemini Generate Content API：

16.14- Generating content | Gemini API | Google AI for Developers

Gemini API 文档首页：