文章 标签 分类 关于我

目录

AI API 的后缀是什么，为什么要这样设计

ByF  收录于  类别 技术实践
     约 3892 字   预计阅读 18 分钟 
从 /v1/completions 到 /v1/responses，AI API 的后缀规定了请求和响应的数据结构，这篇文章把这条链路讲清楚。

我们经常看到这种 URL：

/v1/chat/completions
/v1/messages
/v1/responses

这些后缀不是装饰，它们规定了一套完整的请求和响应数据结构。选错了，代码要么报错，要么丢数据。

这篇文章从 /v1/completions 开始，一路讲到 /v1/responses，把每个后缀代表什么、为什么这么设计、哪些地方容易踩坑说清楚。

先拆一个典型的 API 路径：

https://api.openai.com/v1/chat/completions
        └────────────┬────────────┘
                 API Base URL
                         └─ /v1              API 协议版本
                            └─ /chat         聊天
                                  └─ /completions  生成聊天补全

/v1 约束的是请求字段、响应字段、错误格式、流式事件格式、工具调用格式。同一个模型可能同时支持多种协议，同一个协议也可能被不同厂商支持，但兼容程度不完全一样。

所以问题的本质是：你需要先确认目标平台支持哪种协议，然后按这个协议的规范发请求、收响应。

早期的 LLM 只做一件事：给你一段文本，预测后面的文本。

POST /v1/completions

{
  "model": "gpt-3",
  "prompt": "Translate this sentence into Chinese: Hello, how are you?"
}

模型不知道什么是"系统消息"，什么是"用户输入"，什么是"助手回复"。如果你想做对话，得自己拼：

System: You are a helpful assistant.
User: Hello.
Assistant: Hi, how can I help?
User: Explain API suffixes.
Assistant:

这有两个问题。第一，模型得靠文本格式猜哪部分是谁说的，给了 prompt injection 更多机会。第二，对话历史没法结构化输出，所有上下文都在一整段字符串里。遇到工具调用或图片输入，根本没法优雅处理。

现在这个接口基本是遗留产物了。OpenAI 官方文档把它标记为 Legacy。

这是目前兼容性最好的 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."
    }
  ]
}

messages 数组里的每个对象有 role 和 content：

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

这比手动拼 User:、Assistant: 高明得多。上下文从字符串变成了一组有角色、有顺序的消息对象。

“兼容 OpenAI API"这句话经常被厂商拿来做营销，但兼容是有层级的：

Level 1：普通文本聊天（model + messages + choices）
Level 2：流式输出（stream: true）
Level 3：工具调用（tools + tool_calls）
Level 4：结构化输出（response_format + JSON schema）
Level 5：多模态输入（vision / audio）
Level 6：复杂 agent 事件流

大部分"兼容 OpenAI"的平台只做到 Level 2 或 Level 3。换平台之前先测一下你要用的功能到底支不支持。

因为基础设施已经建好了。SDK、代理、网关、前端聊天软件、RAG 框架都支持 OpenAI Chat Completions 协议。切换平台通常只需要改三个东西：

client = OpenAI(
    api_key="OTHER_PROVIDER_API_KEY",  # 改 key
    base_url="https://api.other.com/v1"  # 改 base URL
)

response = client.chat.completions.create(
    model="other-model",  # 改模型名
    messages=[{"role": "user", "content": "Hello"}]
)

但"能跑"和"完全兼容"是两回事。

Anthropic 选了一条不同的路。

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."
    }
  ]
}

和 OpenAI 的差异主要在三个地方。

OpenAI 把 system 放在 messages 数组里，和其他消息混在一起。Claude 把它提出来作为顶层字段。看起来是小事，但解析逻辑完全不同。

content 是 block 结构

Claude 的 content 可以是字符串，也可以是 content blocks——文本、图片、工具调用结果都是不同类型的 block。

响应解析路径也不同：

OpenAI:    response.choices[0].message.content
Claude:    response.content[0].text

还有 stop_reason、usage.input_tokens、usage.output_tokens 这些字段名也不一样。

OpenAI 和 Claude 的接口结构不兼容，不能直接替换。需要一个适配层做转换。很多第三方平台声称支持 Claude 协议，但实际只是在 OpenAI 兼容层上套了个壳，Claude 特有的功能（比如 extended thinking）不一定能用。

OpenAI 在 2025 年推出的 Responses API 是对 Chat Completions 的重新设计。

POST /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"
    }
  ]
}

/v1/chat/completions 的名字里有两个历史包袱：chat 和 completions。当初的设计假设是用户给一段聊天历史，模型补全下一条消息。

但现在的模型不只聊天了。它要读图片、处理音频、查文件、搜网页、调函数、用代码解释器、维护服务端上下文、输出结构化 JSON、返回推理摘要。把这些全塞进 chat.completion 对象，越来越别扭。

Responses API 的设计思路是：输入是任务、上下文和可用工具，输出是包含文本、工具调用和中间结果的完整响应对象。

Chat Completions:
  输入：messages 数组
  输出：一条 assistant message

Responses:
  输入：input / items
  输出：response object，包含多个 output items

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

但如果涉及工具调用、网页搜索、文件搜索、代码解释器、多模态输入、复杂流式事件、服务端状态、agent workflow，Responses API 更合适。

Gemini 的路径长这样：

POST /v1/models/{model}:generateContent
POST /v1beta/models/{model}:generateContent

拆开看：

  • /v1 或 /v1beta：API 版本
  • /models/{model}：模型资源
  • :generateContent：对这个资源执行的方法

这是 Google API 的标准风格——对某个资源执行某个操作。和 OpenAI、Anthropic 的命名风格明显不同。

数据结构也不一样。Gemini 用 contents + parts，而不是 messages：

OpenAI:     messages -> role + content
Anthropic:  messages -> role + content blocks
Gemini:     contents -> role + parts

v1 是稳定版本，v1beta 是预览能力。生产环境用 v1，想尝鲜再考虑 v1beta。

这个接口把文本变成浮点数向量：

POST /v1/embeddings

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

返回：

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

典型用途是 RAG：用 /v1/embeddings 把文档切片转成向量存入数据库，用户提问时把问题也转成向量，检索最相似的文档片段，再塞进聊天接口生成答案。如果想从零搭建 RAG 系统，可以参考 https://byronfinn.github.io/2025-11-06-rag-system-complete-guide-langchain-ollama-pgvector/。

embedding 负责找资料，聊天接口负责生成答案。两个接口各司其职。

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

查询账号可用的模型、检查模型名称是否正确、动态展示模型选择列表。调试 404 model_not_found 错误时也靠它。

很多人以为 /v1 是第一代模型，/v2 是第二代。这是错的。

/v1 是 API 版本，不是模型版本。

API 版本约束：请求字段、响应字段、错误格式、流式事件、工具调用格式、鉴权方式
模型版本约束：模型能力、大小、上下文长度、推理能力、价格、速度
SDK 版本约束：客户端库的接口变化
协议风格约束：OpenAI-compatible / Anthropic-compatible / Gemini-compatible

这四个不是一回事。

API 版本的存在是为了向后兼容。如果厂商改了响应结构，老代码就废了。所以通常的做法是新开一个版本（/v2）或新增一套接口（/v1/responses），而不是在同一个版本里做破坏性变更。

很多软件配置时会问你填 Base URL 还是 Endpoint。这两个不一样：

Base URL：填到 /v1 为止
  https://api.openai.com/v1
  https://api.groq.com/openai/v1
  https://openrouter.ai/api/v1

Endpoint：填完整路径
  https://api.openai.com/v1/chat/completions

如果软件让你填 Base URL，不要带 /chat/completions，因为 SDK 会自动拼接。填错了，实际请求可能变成：

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

然后报 404。

经验规则：

  • Base URL / API Base / OpenAI Base URL：填到 /v1
  • Endpoint / Full URL / Request URL：填完整路径
  • Provider：选协议类型（OpenAI、Anthropic、Gemini）
  • Model：填模型 ID，不填 URL

这是最容易踩坑的地方。四种协议的响应结构都不一样：

# OpenAI Chat Completions
text = response.choices[0].message.content

# Anthropic Messages
text = response.content[0].text

# OpenAI Responses
text = response.output_text

# Gemini
text = response.candidates[0].content.parts[0].text

写错了不是报错就是拿到空值。切换平台时，响应解析逻辑必须跟着改。

流式输出的格式也不一样。OpenAI 用 data: {"choices":[{"delta":{"content":"Hel"}}]}，Anthropic 用 event: content_block_delta 这种事件流格式。同一个 stream: true 参数，背后的实现完全不同。

厂商接口路径协议风格主要用途
OpenAI/v1/responsesOpenAI 新一代多模态、工具、agent、新项目优先
OpenAI/v1/chat/completionsChat Completions传统聊天、兼容生态
Anthropic/v1/messagesAnthropic 原生Claude 对话、工具、多模态
Google/v1/models/{model}:generateContentGoogle REST 风格Gemini 稳定接口
Mistral/v1/chat/completionsOpenAI-like聊天、工具调用
xAI/v1/chat/completionsOpenAI-likeGrok 对话
DeepSeek/chat/completionsOpenAI-likeDeepSeek 对话模型
Groq/openai/v1/chat/completionsOpenAI-compatible高速推理
OpenRouter/api/v1/chat/completionsOpenAI-compatible多模型聚合路由
  • 简单聊天：/v1/chat/completions，生态最成熟
  • 新项目接 OpenAI，需要现代能力：/v1/responses
  • 接 Claude 官方：/v1/messages，别强行套 OpenAI 壳
  • 接 Gemini：/v1/models/{model}:generateContent
  • 做 RAG：/v1/embeddings + 任意聊天接口
  • 接第三方聚合服务：先确认它兼容哪种协议，再选 SDK。如果想自建 API 代理，可以参考 https://byronfinn.github.io/2026-05-16-self-hosted-ai-api-pipeline/。
AI API 协议演进路径
从 /v1/completions 到 /v1/responses，协议从文本续写演进到统一响应对象
四大协议请求结构对比
OpenAI Chat、Anthropic Messages、OpenAI Responses、Gemini generateContent 的请求结构差异

协议不兼容是常态，兼容是例外。选对协议、填对 Base URL、解析对响应结构，这三件事做对了，调 API 就没什么坑了。

相关内容

从 /v1/completions 到 /v1/responses，AI API 的后缀规定了请求和响应的数据结构，这篇文章把这条链路讲清楚。

Trellis 做了什么，能不能解决 AI 编码的规范问题

一个 PPT Agent 的完整拆解：从需求调研到 SVG 出图

从 /v1/completions 到 /v1/responses，AI API 的后缀规定了请求和响应的数据结构，这篇文章把这条链路讲清楚。

多智能体协作的工程问题：触发、拓扑和收口

从 /v1/completions 到 /v1/responses，AI API 的后缀规定了请求和响应的数据结构，这篇文章把这条链路讲清楚。

AI 时代的精神病：当 MTTR 狂热撞上系统韧性

更新于 2026-06-05  1c3f824
阅读原始文档
 AI, API, OpenAI, Claude, Gemini, 协议设计, REST API
 | 主页