Chat Completions 请求导读
Chat 路径适合兼容现有客户端；如果你需要更复杂的工具和状态管理，建议同时评估 Responses。
POST/v1/chat/completions
Chat Completions 仍然很重要，因为大量上游 SDK、IDE、存量服务都围绕它构建。但它的定位应该是 兼容入口，不一定适合作为所有新能力的默认接口。 如果你只是想把 Cursor、Claude Code、现有 OpenAI-compatible 客户端尽快接进来，这条路径很合适。
最值得先看的参数
| Name | Type | Required | Description |
|---|---|---|---|
model | string | Required | 目标模型标识。兼容接入阶段最常用的入口。 |
messages | array | Required | 对话消息数组。大多数兼容客户端都围绕它构建。 |
stream | boolean | 是否启用流式输出。IDE 和聊天 UI 常用。 | |
tools | array | 工具定义。原始 tool calling 可以工作，但复杂能力更推荐走 Responses / Skills。 | |
models | array | 路由扩展字段，用于多模型候选或 fallback。 | |
provider / route | object | 更细粒度的路由控制。只有你真的需要治理与解释时才该暴露。 |
最小请求
bash
curl -X POST https://api.therouter.ai/v1/chat/completions \
-H "Authorization: Bearer $THEROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "anthropic/claude-sonnet-4.5",
"messages": [
{ "role": "user", "content": "给我一份 deploy checklist。" }
]
}'什么时候它仍然是正确入口
- 你在迁移现有 OpenAI-compatible 客户端，目标是快，不是重新设计输出契约。
- 你要尽快接 Cursor、Claude Code 或已有聊天 UI。
- 你当前主要是单轮或轻量多轮对话，而不是复杂 tools / schema / agent loop。
什么时候该转向 Responses
一旦你开始在 chat 路径里堆 tools、structured outputs、reasoning 控制、多轮状态续写， Responses 往往会更适合。不要只因为兼容旧客户端，就把后续能力长期固定在 chat 抽象上。
最容易犯的错
text
1. 把 chat 当成所有新能力的默认入口。
2. 先暴露复杂 provider / route 控制，而不是先给用户默认值。
3. 想做复杂 tools 和 schema，却还坚持只用 chat 兼容抽象。
4. 试图用 grouped analytics 解释单次 chat 请求异常，而不是看 request logs。