告别 Chat Completions：深度解析 AI 接口新标准 `/v1/responses`

在 2026 年的 AI 开发生态中，开发者们正经历一场从"聊天模型"向"智能体模型"的协议大迁移。如果你在调用 API 时收到了 Unsupported legacy protocol 的错误提示，这意味着你正在使用的供应商已经全面转向了 /v1/responses 协议。

本文将带你深入了解这一新标准的由来、优势以及如何进行适配。

一、背景：为什么旧协议被淘汰了？

自 2023 年以来，/v1/chat/completions 一直是 AI 行业的通用语言。它简单直观：发送 messages 数组，获取 content 字符串。

然而，随着 GPT-5 、Gemini 2.0+ 等高性能模型的发布，旧协议的局限性日益凸显：

/v1/responses 不仅仅是路径的改变，它代表了从 "单次往返" 到 "会话管理" 的思想转变。

特性	旧版 (`/v1/chat/completions`)	新版 (`/v1/responses`)
交互逻辑	无状态（Stateless），需手动传历史	有状态（Stateful），支持 `store: true`
数据结构	核心字段为 `messages`	核心字段变为 `input` 或 `instructions`
推理展示	仅输出最终结果	原生支持 `reasoning_content` (思维链)
性能优化	依赖客户端缓存	支持服务器端上下文压缩 (Compaction)
工具扩展	简单的 Function Call	深度集成 MCP (Model Context Protocol)

观察 Endpoint ：检查 API 文档中的 Base URL。如果包含 /openai/v1/ 且路径强制要求 /responses，说明已完成进化。
模型后缀 ：关注模型列表中是否有 -legacy。没有该后缀的新模型通常优先适配新协议。
技术探测 ：使用 Curl 测试 /v1/responses 路径。若返回 401 或参数错误而非 404，说明协议已部署。

当你准备从旧协议迁移时，主要需要调整请求体的结构。以下是一个典型的对比示例：

json 复制代码

{
  "model": "gpt-4o",
  "messages": [{"role": "user", "content": "你好"}]
}

json 复制代码

{
  "model": "gpt-5-preview",
  "input": "你好",
  "store": true,
  "metadata": { "user_id": "elixia_01" },
  "tools": [{ "type": "web_search" }]
}

注意：新协议通常支持 store: true 参数。开启后，你无需在下一次请求中发送之前的对话，服务器会自动关联 session_id。

/v1/responses 的普及标志着 AI Agent 时代的正式到来。它通过标准化的状态管理和推理展示，让开发者能够构建更聪明、更省钱、响应更快的应用。

对于开发者而言，目前的最佳实践是：