/v1/chat/completions、/v1/responses、/v1/messages 有什么区别？端点选错为什么会导致模型不可用

/v1/chat/completions vs /v1/responses vs /v1/messages：应该使用哪个 AI API 端点？#

AI API 网关中的常见支持问题不在 API 密钥、不在模型、也不在 SDK。问题在于端点。

用户选择了一个存在的模型，但将请求发送到了错误的端点。结果看起来像：

• 模型不可用；
• 不支持的端点；
• 无效的请求体；
• 工具调用不工作；
• 流式格式不匹配；
• Claude 模型在一个工具中工作，但在另一个工具中失败。

本指南解释了三个端点族之间的区别：

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

简短版本：

如果您的客户端说"OpenAI 兼容"，从以下开始：

https://crazyrouter.com/v1/chat/completions

或将 Base URL 设置为：

https://crazyrouter.com/v1

并让 SDK 追加 /chat/completions。

如果您的工具特别需要 OpenAI Responses API，使用 /v1/responses。

如果您的工具是 Anthropic 本地工具且期望 Claude 的 Messages API，使用 /v1/messages。

最常见的错误#

最常见的错误是混合模型族和端点族。

例如，Claude 模型可以通过 OpenAI 兼容网关公开，但这并不自动意味着您的请求体应该使用 Anthropic 的本地 /v1/messages schema。

同样，发送 Anthropic 本地请求到 /v1/messages 的工具不能仅通过更改模型名称来修复。端点和请求体必须匹配。

这样想：

model name + endpoint + request schema must match

如果三者中的任何一个错误，即使模型本身是健康的，模型看起来也可能不可用。

什么是 /v1/chat/completions#

/v1/chat/completions 是经典的 OpenAI 兼容聊天端点。

典型的请求如下所示：

curl https://crazyrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $CRAZYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Explain API endpoints in one paragraph."}
    ]
  }'

在以下情况使用 /v1/chat/completions：

• 应用说它支持 OpenAI 兼容 API；
• 配置要求 OPENAI_BASE_URL 或 base_url；
• 请求体使用带有 role 和 content 的 messages；
• 您使用常见的 OpenAI SDK 兼容模式；
• 您正在配置 Cursor 风格客户端、LiteLLM 风格路由器、FastGPT 风格应用或许多聊天 UI 等工具。

对于许多用户来说，这是最安全的默认端点。

什么是 /v1/responses#

/v1/responses 是较新的 OpenAI Responses API 端点。

它围绕一个更通用的响应对象设计，可以表示以下事项：

• 文本输出；
• 工具调用；
• 多模态输入；
• 推理项；
• 结构化输出；
• 类代理工作流。

简化的请求如下所示：

curl https://crazyrouter.com/v1/responses \
  -H "Authorization: Bearer $CRAZYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "Explain the difference between chat completions and responses."
  }'

在以下情况使用 /v1/responses：

• 工具明确说它使用 OpenAI Responses API；
• 配置提及 responses 而不是 chat.completions；
• 请求体使用 input 而不是 messages；
• 模型/提供商路由支持 Responses API 行为；
• 您需要较新的 OpenAI 风格工具或推理输出格式。

除非网关明确记录转换，否则不要向 /v1/responses 发送聊天完成体。

什么是 /v1/messages#

/v1/messages 是 Anthropic Messages API 风格的端点。

典型的 Claude 本地请求如下所示：

curl https://crazyrouter.com/v1/messages \
  -H "Authorization: Bearer $CRAZYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "system": "You are a helpful assistant.",
    "messages": [
      {"role": "user", "content": "Explain Claude Messages API."}
    ]
  }'

在以下情况使用 /v1/messages：

• 客户端是 Anthropic 本地工具；
• SDK 期望 Claude Messages API 格式；
• 请求在顶级使用 system 而不是数组内的系统消息；
• 请求需要 Anthropic 特定的内容块或工具 schema；
• 文档明确说调用 /v1/messages。

不要假设每个 Claude 模型都应该用 /v1/messages 调用。如果您使用 OpenAI 兼容网关或 SDK，Claude 模型可能通过 /v1/chat/completions 调用。

为什么端点错误会让模型看起来不可用#

当模型失败时，用户经常假设模型已关闭。但在许多情况下，模型很好，请求格式是错误的。

常见的不匹配示例：

Base URL vs 完整端点#

许多工具要求 Base URL，而不是完整端点。

正确的 Base URL：

https://crazyrouter.com/v1

然后 SDK 调用：

https://crazyrouter.com/v1/chat/completions

大多数 SDK 的错误 Base URL：

https://crazyrouter.com/v1/chat/completions

为什么？因为 SDK 可能再次追加 /chat/completions。

规则：

• 如果字段称为 base_url，使用 /v1。
• 如果字段称为 endpoint 并要求完整 URL，使用工具需要的完整路径。

我应该选择哪个端点？#

使用此决策树：

1. 您的工具说"OpenAI 兼容 API"吗？
   使用 /v1/chat/completions 或 Base URL https://crazyrouter.com/v1。

2. 您的工具具体说"Responses API"吗？
   使用 /v1/responses。

3. 您的工具使用 Anthropic SDK 或 Claude Messages API 吗？
   使用 /v1/messages。

4. 您不确定吗？
   从 /v1/chat/completions 开始，因为大多数第三方客户端支持它。

推荐的 Crazyrouter 配置#

对于大多数 OpenAI 兼容工具：

API Key: your Crazyrouter API key
Base URL: https://crazyrouter.com/v1
Model: choose a model from the Crazyrouter model list

对于全球路由不稳定的地区的用户：

Base URL: https://cn.crazyrouter.com/v1

人类可读的链接可以使用 UTM 跟踪：

https://crazyrouter.com/models?utm_source=blog&utm_medium=article&utm_campaign=api_endpoints

API 端点不应该：

https://api-endpoint.example.invalid/v1?utm_source=blog

快速调试清单#

报告"模型不可用"之前，检查以下五个事项：

1. 模型名称的拼写是否与模型列表中显示的完全一致？
2. 端点族是否正确：聊天完成、响应或消息？
3. 请求体是否与该端点的 schema 匹配？
4. Base URL 是否完全是 /v1，不是缺少它也不是重复端点路径？
5. 您是否使用正确的 SDK 模式：OpenAI 兼容或 Anthropic 本地？

最终建议#

如果您正在构建通用应用集成，从 /v1/chat/completions 开始。它是最广泛的兼容性路径。

当您的客户端或工作流明确需要 Responses API 时，使用 /v1/responses。

当您使用 Anthropic 本地工具时，使用 /v1/messages。

当您记住这条规则时，大多数端点问题都会消失：

OpenAI-compatible client → /v1/chat/completions
OpenAI Responses client → /v1/responses
Anthropic-native client → /v1/messages

如果模型存在但看起来不可用，不要仅更改模型名称。首先检查端点和请求 schema。