大模型 API 的 URL 是谁设计的

接大模型 API 的通用做法：把 base_url 换成厂商域名，模型名改一行，其他代码不动。

前提是厂商提供同一个路径。/v1/chat/completions 这个路径，DeepSeek、Moonshot、智谱、阿里、Groq、OpenRouter 都在用。

这个路径不是标准组织发布的标准，也没有公开的设计者名单。

它从哪来，为什么长这样，各家为什么又不太一样，本文把能查到的出处整理一遍。

先说结论

「谁设计的」没有一个单独的答案。可查证的事实分四段。

第一段，2000 到 2016 年。/v1 版本段、资源名词路径、JSON、Bearer Token 这套惯例在 REST 云服务里已经收敛。作者是一批公司，不是一个人。

第二段，2020 年 6 月 11 日。OpenAI API 上线，端点是 POST /v1/engines/{engine}/completions。LLM API 的 URL 结构从这天开始有了原型。

第三段，2023 年 3 月 1 日。OpenAI 发布 chat/completions，请求体改成 messages 数组。公告署名八个人。这是唯一一段能落到具体人名的。

第四段，2023 年之后。各家要么整体沿用 OpenAI 格式，要么另立原生格式再补一个兼容层。

下面分段展开，每段附出处。

/v1、JSON、Bearer：早于大模型的惯例

REST 出自 Roy Fielding 2000 年的博士论文第 5 章。

论文定义的是一种架构风格，不是协议，也没有规定版本号必须写在路径里 ¹。

把版本写进路径，有两个明确的出处。

一个是 Twitter。2012 年 8 月 16 日，Twitter 开发者博客公告 API v1.1，路径从 /1 换成 /1.1 ²。

另一个是 Microsoft。Microsoft REST API Guidelines 明文规定，版本 “MUST embed the version in the URL path” ³。

Bearer Token 出自 RFC 6750，2012 年 ⁴。

Stripe 从 2011 年开始把 API 当产品维护，2017 年的工程博客详细写了它的版本化制度 ⁵。

也就是说，2020 年之前，/v1 加资源名词加 JSON 加 Bearer，已经是云服务 API 的常见组合。

大模型 API 继承的是这套东西。

OpenAI 的三个端点

OpenAI 自家端点的变更记录，是这条路径最直接的时间线。

2020 年 6 月 11 日：/v1/engines/{engine}/completions。

OpenAI API 上线，官方定位是通用文本接口，原话 “text in, text out” ⁶。

端点按模型（engine）寻址。原版文档页已经下线，端点形态依据多方转引 ⁷。

2023 年 3 月 1 日：/v1/chat/completions。

OpenAI 发布 gpt-3.5-turbo，公告原话：”the same model used in the ChatGPT product” ⁸。

请求体从裸 prompt 字符串改成 messages 数组。

公告署名八人：Greg Brockman、Atty Eleti、Elie Georges、Joanne Jang、Logan Kilpatrick、Rachel Lim、Luke Miller、Michelle Pokrass。

署名说明这八人对发布负责。URL 结构具体出自谁手，公开资料里查不到。

2025 年 3 月 11 日：/v1/responses。

官方称 Responses API 是 Chat Completions 的 superset，同时承诺继续支持旧端点，原话 “Chat Completions remains our most widely adopted API” ⁹。

三代端点的现状：

两点补充。

第一，/v1 前缀从 2020 年用到今天，v2 从未出现。退役的是端点（engines、edits、Assistants API），不是版本段 ¹⁰。

第二，退役有固定程序。官方 deprecations 页区分 deprecation、sunset、legacy 三个词，GA 模型停用至少提前六个月通知 ¹⁰。

还有一个细节：chat/completions 的路径里保留了 completions 这个词。

消息对话在语义上已经不是「补全一段文本」。这个词根是 2023 年从上一代端点继承下来的。

版本号为什么写在路径里

版本化在业界本来有两派。

path 派把版本写进 URL，代表是 Twitter 和 Microsoft。

header 派把版本放进 Accept 头，URL 不变，代表是 Heroku 和 GitHub ¹¹。

Stripe 是第三种：日期滚动的 API 版本，配 Stripe-Version 请求头，可以按请求覆盖 ⁵。

Stripe 对 path 大版本方案有一句直接的批评，大版本之间的变化 “so big and so impactful for users that it’s almost as painful as re-integrating from scratch” ⁵。

OpenAI 选的恰恰是 path 方案。

结果是大模型行业整体采用路径版本，header 版本化在 LLM API 里几乎没有使用者。

2026 年 9 月的格式版图

到本文写作时，行业主流的请求格式有三套：OpenAI Chat Completions、OpenAI Responses、Anthropic Messages。

各家的 URL 长这样：

几个具体例子。

Azure 的路径是 /openai/deployments/{deployment-id}/chat/completions?api-version=<版本>，部署 ID 和版本号都嵌在 URL 里 ¹²。

AWS Bedrock 的原生路径是 /model/{modelId}/invoke，2025 年 8 月另上线了 OpenAI 兼容接口 ¹³。

Gemini 的原生方法是 POST /models/{model}:generateContent。

冒号加动词的命名来自 Google 全公司的 API 规范 AIP-136：自定义方法的 URI 形态是资源名加冒号加动词 ¹⁴。它的 OpenAI 兼容路径是 /v1beta/openai/chat/completions ¹⁵。

本地推理栈全线默认提供 OpenAI 路径：vLLM 的 /v1/chat/completions ¹⁶；Ollama 在 2024 年 2 月 8 日官宣内置 OpenAI 兼容 ¹⁷。

兼容层的实际限制

所有提供「原生格式 + OpenAI 兼容层」的厂商，都在文档里写明兼容层功能不全。

Anthropic 的兼容文档原文：”The strict parameter for function calling is ignored. Audio input is not supported; it will be ignored and stripped” ¹⁸。

意思是 tool calling 的严格模式被忽略，音频输入会被剥离。

Gemini 的兼容文档标注 beta，原话：”Any other parameters not listed here or in the extra_body section will be silently ignored by the compatibility layer” ¹⁵。

cached_content、thinking_config 这些 Gemini 特有参数，要走 extra_body 字段传入 ¹⁵。

Bedrock 的兼容接口，第三方报道的评价是 “API Parity, But Not Quite Full Compatibility”（出处见文末未核实清单）。

所以「改个 base_url 就能迁移」覆盖的是基础报文。

tool calling 的严格模式、音频输入、思考链、缓存控制，各家兼容层的支持程度不一样。

接生产之前，需要逐项对照厂商的限制清单。

中国厂商的接入方式

DeepSeek 的 API 文档第一句是：

DeepSeek API 使用与 OpenAI/Anthropic 兼容的 API 格式，通过修改配置，您可以使用 OpenAI/Anthropic SDK 来访问 DeepSeek API，或使用与 OpenAI/Anthropic API 兼容的软件。¹⁹

2024 到 2025 年的版本里只有 OpenAI。2026 年起加入 Anthropic 协议，base_url 为 https://api.deepseek.com/anthropic ¹⁹。

智谱在 2025 年 9 月上线 Claude API 兼容页，原话「只需修改 API 密钥和基础 URL，即可无缝切换至 GLM 模型 API」²⁰。

兼容的直接动机是迁移成本。开发者不用换 SDK，one-api 这类统一网关也按 OpenAI 格式做接入 ²¹。

价格是另一个维度。2025 年 2 月调价后，deepseek-chat 每百万 tokens 输入（缓存命中）0.5 元，输出 8 元 ²²。

作为对比，GPT-4o 的定价是每百万 tokens 输入 2.5 美元、输出 10 美元（2024 年）²³。

兼容报文之下，各家保留了自己的路径习惯：

• 阿里百炼：/compatible-mode/v1，兼容与原生双轨 ²⁴
• 智谱：/api/paas/v4，自有版本号 ²⁵
• 火山方舟：/api/v3，把 endpoint 作为 model 参数传 ²⁶
• DeepSeek：/v1 与模型版本无关，旧版文档注明「此处 v1 与模型版本无关」，纯粹为兼容 SDK 而保留 ¹⁹

新能力也发生在旧格式上。

2025 年 1 月 20 日，DeepSeek 发布 R1，思维链通过在 chat/completions 格式上加 reasoning_content 字段承载 ²⁷。

为什么这个路径不容易改

先看传输协议的三个事实。

请求和响应是 JSON，不是二进制格式。

流式输出用 SSE（text/event-stream），OpenAI 和 Anthropic 的 API 参考文档都是如此 ²⁸。

双向实时会话是例外。OpenAI 的 Realtime API（2024 年 10 月）用 WebSocket 承载音频 ²⁹。

单向文本流走 SSE，双向实时会话换协议，边界是清楚的。

再看改动为什么困难。Hyrum’s Law 的原文：

With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody.
—— Hyrum Wright ³⁰

用户足够多之后，契约承诺什么不重要，用户依赖的是全部可观察行为。

OpenAI 对 chat/completions 的处理方式与此一致：旧端点承诺不动，新范式另起 /v1/responses ⁹。

端点确实会退役。Assistants API 2023 年 11 月发布，2026 年 8 月退役，生命周期约三年 ¹⁰。

但退役的端点不会被原地改造，替代者是新 URL。

2026 年的实际分歧在这里。

The New Stack 称 OpenAI 已在 2025 年 3 月完成向 Responses 的过渡 ³¹。

xAI 的文档把 Chat Completions 标为 Legacy ³²。

Codex 类工具只支持 Responses API。36氪出海 2026 年 6 月实测，国产模型因此接不进 Codex ³³。DeepSeek V4-Flash 在 2026 年 7 月宣布原生支持 Responses API ³⁴。

官方口径是旧端点继续支持，生态工具在向新端点迁移。两种说法并存，本文不下结论。

标准化方面，截至 2026 年 9 月，模型 HTTP API 层没有正式标准。

信通院 2026 年 8 月底发布的大模型平台系列行业标准，覆盖的是平台生命周期，不含接口格式 ³⁵。

ITU-T 的 AICP 系列面向智算平台架构，也不在这层 ³⁶。

例外是 MCP。2024 年 11 月 25 日由 Anthropic 发布 ³⁷，作用在 agent 与工具、数据之间，与模型 HTTP API 是不同的层，同样由单一公司发起。

最后

两条实际的提醒。

一，「OpenAI 兼容」只保证基础报文一致。高级能力（严格 tool calling、音频、思考链、缓存）在兼容层里支持不一，上生产前查官方限制清单。

二，观察格式走向，看谁的新端点、新字段被其他厂商兼容，比看宣传口径可靠。

未能核实的事项

• Anthropic Messages API 的首发日期：2023-05 与 2023-11 两种说法并存，未检索到一手 release note，本文未采用具体日期。
• 2020 年 OpenAI 原版文档页已下线，/v1/engines/{engine}/completions 的形态依据多方转引 ⁷。
• Bedrock 兼容接口 “API Parity, But Not Quite Full Compatibility” 一句出自 2025 年 8 月 DEV Community 的第三方报道，原链接未能核实。
• 阿里百炼兼容层的确切上线日期未核实（2024 年 8 月已有社区记录）。

来源

以下为本文引用的全部出处，访问时间除注明外均为 2026-09-22。

1. Roy T. Fielding. Architectural Styles and the Design of Network-based Software Architectures（第 5 章 Representational State Transfer）. UC Irvine 博士论文, 2000. https://roy.gbiv.com/pubs/dissertation/rest_arch_style.htm ↩︎
2. Twitter Developer Blog. “Changes coming in Version 1.1 of the Twitter API”. 2012-08-16.（原 blog.twitter.com，现收录于 x.com 开发者博客存档） ↩︎
3. Microsoft. Microsoft REST API Guidelines（v7.1.1）. https://github.com/microsoft/api-guidelines ↩︎
4. IETF. RFC 6750: The OAuth 2.0 Authorization Framework: Bearer Token Usage. 2012-10. https://datatracker.ietf.org/doc/html/rfc6750 ↩︎
5. Stripe Engineering. “APIs as infrastructure: future-proofing Stripe with versioning”. 2017. https://stripe.com/blog/api-versioning ↩︎
6. OpenAI Blog. “OpenAI API”. 2020-06-11. https://openai.com/index/openai-api/ ↩︎
7. 2020 年端点形态转引来源：O’Reilly《Exploring GPT-3》第 1 章（转引 OpenAI 公告原文）. https://www.oreilly.com/library/view/exploring-gpt-3/9781800563193/B16854_01_ePub_AM.xhtml ↩︎
8. OpenAI Blog. “Introducing ChatGPT and Whisper APIs”. 2023-03-01. https://openai.com/index/introducing-chatgpt-and-whisper-apis ↩︎
9. OpenAI Blog. “New tools for building agents”. 2025-03-11. https://openai.com/index/new-tools-for-building-agents/ ↩︎
10. OpenAI Platform Docs. “Deprecations”. 抓取于 2026-09-22. https://platform.openai.com/docs/deprecations ↩︎
11. Heroku. Platform API Reference. https://devcenter.heroku.com/articles/platform-api-reference ；interagent. HTTP API Design Guide. https://github.com/interagent/http-api-design （Heroku 官方条文原文未直接核到，条文表述转引自 HTTP API Design Guide） ↩︎
12. Microsoft Learn. Azure OpenAI Service REST API reference. https://learn.microsoft.com/en-us/azure/ai-services/openai/reference ↩︎
13. AWS. Amazon Bedrock User Guide. https://docs.aws.amazon.com/bedrock/latest/userguide/ ↩︎
14. Google. AIP-136: Custom methods（API Improvement Proposals）. https://google.aip.dev/136 ↩︎
15. Google AI for Developers. “Open AI compatibility — Gemini API docs”. 更新于 2026-09-02. https://ai.google.dev/gemini-api/docs/openai ↩︎
16. vLLM Official Documentation. OpenAI-Compatible Server. https://docs.vllm.ai/ ↩︎
17. Ollama Blog. “OpenAI compatibility”. 2024-02-08. https://ollama.com/blog/openai-compatibility ↩︎
18. Claude Platform Docs. OpenAI SDK compatibility — OpenAI compatibility limitations. https://platform.claude.com/ ↩︎
19. DeepSeek API 文档（中文站）. https://api-docs.deepseek.com/zh-cn/ ↩︎
20. 智谱 CSDN 官方号.《中国开发者！Claude 全面禁用后，智谱为大家准备了「省心」替代》. 2025-09-08.（引文为逐字转引，具体文章页 URL 未能核实） ↩︎
21. one-api GitHub README（OpenAI API 格式统一网关）. https://github.com/songquanpeng/one-api ↩︎
22. DeepSeek. Models & Pricing. https://api-docs.deepseek.com/quick_start/pricing （2025-02-08 调价口径） ↩︎
23. OpenAI Pricing. https://openai.com/api/pricing/ （GPT-4o，2024 年口径） ↩︎
24. 阿里云. OpenAI Chat 接口兼容 — 阿里云百炼文档. https://help.aliyun.com/zh/model-studio/compatibility-of-openai-with-dashscope ↩︎
25. 智谱 AI 开放平台文档. https://docs.bigmodel.cn/ ；https://open.bigmodel.cn/dev/api ↩︎
26. 火山引擎方舟文档. https://www.volcengine.com/docs/82379/1263279 ↩︎
27. DeepSeek 官方公告.《深度更新｜DeepSeek-R1 发布，性能对标 OpenAI o1 正式版》. 2025-01-20. https://api-docs.deepseek.com/zh-cn/news/news250120 ↩︎
28. OpenAI Platform Docs. Streaming（API Reference）. https://platform.openai.com/docs ；Claude Platform Docs. Streaming（API Reference）. https://platform.claude.com/ ↩︎
29. Realtime API 使用 WebSocket 一事为二手转述：Towards Data Science（2024-10）、jambonz 对 Realtime API 的分析. https://towardsdatascience.com/ ；https://jambonz.org/ ↩︎
30. Hyrum Wright. Hyrum’s Law: An observation on Software Engineering. https://www.hyrumslaw.com/ ↩︎
31. The New Stack. “Open Responses vs. Chat Completion: A new era for AI apps”. 2026-01-27. https://thenewstack.io/ ↩︎
32. xAI. Grok API Quickstart（Chat Completions 标注 Legacy）. 2026-08-18. https://docs.x.ai/ ↩︎
33. 36氪出海.《Codex兼容国产开源模型，实测DeepSeek接入：门槛还是太高》. 2026-06-21. https://eu.36kr.com/ （具体文章页 URL 未能核实） ↩︎
34. 知乎专栏.《DeepSeek V4-Flash 正式版来啦，原生支持Response API》. 2026-07-31 ；Apidog. “DeepSeek-V4-Flash Now Supports the Responses API”. 2026-07-31.（均为二手报道） ↩︎
35. 中国信通院牵头的大模型平台系列行业标准发布（第一财经等多源报道）. 2026-08-31. https://www.yicai.com/ （具体报道 URL 未能核实） ↩︎
36. 北京信息化协会.《中国信通院启动「ITU-T AICP 系列国际标准」典型产品征集工作》. 2024-11-18. https://www.bita.org.cn/ ↩︎
37. Anthropic. “Introducing the Model Context Protocol”. 2024-11-25. https://www.anthropic.com/news/model-context-protocol ↩︎