深度解析 AI API 接口协议：从 /v1/chat/completions 到 /v1/responses

背景

在接入大语言模型（LLM）时，开发者经常会在 API Base URL 后看到各种各样的路径后缀，例如 /v1/chat/completions、/v1/responses、/v1/messages、/v1/embeddings 等。这些后缀并非随意命名，而是模型厂商为模型能力规定的一套接口协议。

不同的后缀代表了不同的通信规范，约束了请求字段、响应格式、错误处理、流式事件以及工具调用等细节。同一个模型可能支持多种协议（如 OpenAI 的模型既支持 /v1/chat/completions 也支持 /v1/responses），而不同的平台（如 Mistral、xAI、DeepSeek、Groq、OpenRouter）也可能对同一协议有不同的兼容程度。理解这些协议的设计初衷和演进逻辑，是高效构建 AI 应用的基础。

核心内容

1. 接口路径的构成与含义

API 路径通常由 Base URL + 版本 + 功能模块 + 具体操作 组成。以 https://api.openai.com/v1/chat/completions 为例：

• API Base URL: https://api.openai.com/v1
• API 协议版本: /v1
• 功能模块: /chat（聊天）
• 具体操作: /completions（生成补全）

其他常见路径及其核心功能如下：

• /v1/completions: 早期文本续写接口。
• /v1/chat/completions: 聊天回复接口，目前最广泛兼容。
• /v1/messages: Anthropic (Claude) 风格的消息处理接口。
• /v1/responses: OpenAI 推出的更通用的多模态、多工具、多事件响应接口。
• /v1beta/models/{model}:generateContent: Google Gemini 风格，对资源执行方法。
• /v1/embeddings: 向量化接口。
• /v1/models: 查询可用模型资源。

2. /v1/completions：早期的文本续写

早期的大语言模型本质上是“文本补全”模型。用户传入一段 Prompt，模型预测后续文本。

• 请求结构：仅包含 model 和 prompt（字符串）。
• 局限性：
  • 缺乏角色概念：模型不知道什么是系统指令、用户输入或助手回复。开发者需手动拼接 System: ... User: ... 等前缀，这容易导致提示词注入或“破限”。
  • 上下文非结构化：历史对话以长字符串形式存在，难以优雅地处理工具调用或多模态输入（图片、音频）。
• 现状：随着 Chat 接口的普及，/v1/completions 已逐渐变为旧式接口。

3. /v1/chat/completions：行业通用的聊天协议

这是过去几年最重要、兼容性最广的 LLM API 协议，由 OpenAI 定义，并被广泛模仿。

• 核心结构：

  • messages 数组：将对话结构化为对象列表，包含 role（角色）和 content（内容）。
  • choices 返回值：包含模型生成的回复。

• 角色定义：

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

• 优势：

  • 结构化：避免了手动拼接文本，上下文以结构化消息组传递。
  • 广泛兼容：Mistral、xAI、DeepSeek、Groq、OpenRouter 等平台均支持此协议（路径可能略有不同，如 /chat/completions 或 /openai/v1/chat/completions）。

• 工程便利性：由于基础设施完善，切换提供商通常只需修改 base_url、api_key 和 model。

  # 示例：从 OpenAI 切换到兼容服务
  client = OpenAI(
      api_key="OTHER_PROVIDER_API_KEY",
      base_url="https://api.other-provider.com/v1"
  )
  

• 兼容性的层级： 虽然都叫 OpenAI-compatible，但兼容程度不同：

  • Level 1: 普通文本聊天兼容。
  • Level 2: 支持流式输出。
  • Level 3: 支持函数调用/工具调用。
  • Level 4: 支持结构化输出。
  • Level 5: 支持多模态输入。
  • Level 6: 支持复杂 Agent 事件流和状态管理。
  • 注意：许多平台可能仅支持前几层，不支持 parallel_tool_calls、json_schema_strict_mode 或复杂的流式工具调用 Delta。

4. /v1/messages：Anthropic (Claude) 的消息协议

Anthropic 推出了自己的协议 /v1/messages，虽然看起来相似，但与 OpenAI 协议存在关键差异，不能直接通用。

• 核心差异：

  1. System 指令位置：
     • OpenAI: messages 数组中包含 role: "system" 的对象。
     • Anthropic: system 是顶层字段，独立于 messages 数组。
  2. Content 结构：
     • Anthropic 强调 content blocks（内容块）。内容可以是字符串，也可以是包含文本、图片、工具调用结果等不同类型的 Block。
  3. 响应解析：
     • OpenAI: choices[0].message.content
     • Anthropic: content[0].text，且响应中包含 stop_reason、usage 等字段。

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

5. /v1/responses：OpenAI 的统一响应对象

为了应对更复杂的多模态、多工具和多事件场景，OpenAI 推出了 /v1/responses 接口，旨在提供更现代化的统一规范。

• 设计理念：

  • 更通用的 input 和 output 结构。
  • 支持 items、tools、stateful response（有状态响应）。
  • 请求结构更加细化，例如 input 可以是包含 role 和 content 数组的对象，其中 content 进一步细分为 type（如 input_text）和具体文本。

  // /v1/responses 请求示例
  {
    "model": "gpt-5.5",
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "Search the web and summarize the result."
          }
        ]
      }
    ],
    "tools": [
      {
        "type": "web_search"
      }
    ]
  }
  

关键要点

• 协议即规范：API 路径后缀规定了请求/响应的数据结构、鉴权、错误处理、流式输出及工具调用规范。
• 兼容性陷阱：虽然 /v1/chat/completions 是事实标准