# Chat Completions

> POST /v1/chat/completions 的请求字段、响应结构与流式行为。

```
POST https://api.tokrouter.dev/v1/chat/completions
Authorization: Bearer sk-…
Content-Type: application/json
```

这是最通用的入口:OpenAI 协议,绝大多数客户端与框架默认走它。

## 请求字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 模型 id,见[模型](/zh/models/) |
| `messages` | array | 是 | 消息数组,元素含 `role`(`system` / `user` / `assistant` / `tool`)与 `content` |
| `stream` | boolean | 否 | `true` 时返回 SSE,见[流式输出](/zh/guides/streaming/) |
| `max_tokens` | integer | 否 | 输出 token 上限 |
| `temperature` | number | 否 | 采样温度 |
| `top_p` | number | 否 | 核采样 |
| `stop` | string / array | 否 | 停止词 |
| `tools` | array | 否 | function calling 的工具声明,见[工具调用](/zh/guides/tool-calling/) |
| `tool_choice` | string / object | 否 | `auto` / `none` / 指定函数 |
| `response_format` | object | 否 | 结构化输出约束,见[结构化输出](/zh/guides/structured-output/) |
| `user` | string | 否 | 调用方自定义的终端用户标识 |

<Callout type="info" title="字段是 OpenAI 协议的子集">
网关按 OpenAI Chat Completions 语义解释请求,再映射到目标厂商。厂商独占字段不保证生效 ——
见[协议互转](/zh/guides/protocol-interop/)的「已知边界」。
</Callout>

## 响应

```json
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1793000000,
  "model": "gpt-5.4-mini",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "你好"},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 3,
    "total_tokens": 15
  }
}
```

`usage` 里的 `prompt_tokens_details.cached_tokens`(若有)对应缓存读的计费部分。

## 流式

`stream: true` 时,每个 chunk 是 `choices[0].delta`,以 `data: [DONE]` 结束。
`usage` 通常只出现在最后一个 chunk(部分上游不返回)。

## 状态码

| 状态码 | 含义 |
| --- | --- |
| `200` | 成功(流式时也是 200,错误发生在流建立之后会以事件形式出现) |
| `400` | 请求体不合法,例如 `model` 不存在 |
| `401` | 鉴权失败,见[鉴权](/zh/authentication/) |
| `429` | 限流或额度上限 |
| `5xx` | 上游厂商错误 |

具体的错误 `type` / `code` 来自上游,不在本页枚举。