> ## Documentation Index
> Fetch the complete documentation index at: https://docs.focusapi.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 附录：Chat Completions

> FocusAPI Chat Completions 附录参考：POST /v1/chat/completions 端点、请求字段、流式输出和响应结构。

## 端点

```http theme={null}
POST /v1/chat/completions
```

Base URL：`https://www.focusapi.cn/v1`

## 请求头

| 头               | 必填 | 说明                       |
| --------------- | -- | ------------------------ |
| `Authorization` | 是  | `Bearer sk-your-api-key` |
| `Content-Type`  | 是  | `application/json`       |

## 请求体（常用字段）

| 字段            | 类型      | 说明                                              |
| ------------- | ------- | ----------------------------------------------- |
| `model`       | string  | 模型 ID，见模型广场                                     |
| `messages`    | array   | 对话消息列表，`role` 为 `system` / `user` / `assistant` |
| `stream`      | boolean | `true` 时以 SSE 流式返回                              |
| `temperature` | number  | 采样温度，可选                                         |
| `max_tokens`  | integer | 最大生成 token 数，可选                                 |

### 最小示例

```json theme={null}
{
  "model": "gpt-4o-mini",
  "messages": [
    { "role": "user", "content": "你好" }
  ]
}
```

完整可复制命令见 [快速开始](/quickstart)，按能力说明见 [文本对话](/models/chat)。

## 流式输出

设置 `"stream": true` 后，响应为 **Server-Sent Events (SSE)**，每行以 `data: ` 开头。

Python SDK 示例：

```python theme={null}
stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "你好"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
```

<Warning>
  流式请求请设置合理的客户端读超时；长时间无数据可能遇到 [524 超时](/errors/524)。
</Warning>

## 响应（非流式）

成功时 HTTP **200**，JSON 结构兼容 OpenAI，例如：

```json theme={null}
{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}
```

`usage` 用于计费参考，具体扣费规则见 [计费说明](/billing/pricing)。

## 错误

| 状态码 | 文档                 |
| --- | ------------------ |
| 401 | [未授权](/errors/401) |
| 429 | [限流](/errors/429)  |
| 524 | [超时](/errors/524)  |

## 按能力查阅

* [文本对话](/models/chat)
* [推理模型](/models/reasoning)
* [多模态理解](/models/multimodal)
* [工具调用](/models/tool-calling)