聊天补全 API 文档 (Chat Completions)

该 API 用于给定一系列对话消息，模型将返回一个或多个预测的补全结果。支持流式输出、工具调用（Function Calling）以及多种采样参数调整。

1. 接口信息

接口名称：官方N测试
请求方法：POST
请求地址：https://api.codingplanx.ai/v1/chat/completions
内容类型：application/json
认证方式：Bearer {{YOUR_API_KEY}}

2. 请求头 (Headers)

参数名	必选	类型	说明	示例
Content-Type	是	string	媒体类型标识	`application/json`
Accept	是	string	客户端接收的响应格式	`application/json`
Authorization	否	string	API 访问令牌	`Bearer sk-xxxxxx`

3. 请求体 (Request Body)

参数名	必选	类型	说明
model	是	string	要使用的模型 ID（如 `gpt-4o`, `gpt-3.5-turbo`）。
messages	是	array	对话消息列表。每个对象包含 `role` (system/user/assistant) 和 `content`。
tools	是	array	模型可以调用的一组工具列表。目前仅支持函数。
tool_choice	是	object	控制模型调用哪个函数。`none` (不调用), `auto` (自动), 或指定具体函数。
temperature	否	number	采样温度 (0-2)。越高越随机，越低越确定。建议与 `top_p` 二选一调整。
top_p	否	number	核采样。0.1 表示只考虑前 10% 概率质量的标记。
n	否	integer	默认为 1。为每个输入消息生成的回复数量。
stream	否	boolean	默认为 false。如果为 true，则像 ChatGPT 一样发送增量标记。
stop	否	string	停止序列。当模型遇到这些字符时停止生成。
max_tokens	否	integer	生成的最大标记数。默认为 inf。
presence_penalty	否	number	-2.0 到 2.0 之间。惩罚已出现过的主题，增加谈论新话题的可能性。
frequency_penalty	否	number	-2.0 到 2.0 之间。惩罚重复的字词。
logit_bias	否	object	修改指定标记出现的可能性。
user	否	string	终端用户标识符，用于检测滥用。
response_format	否	object	指定返回格式。例如 `{ "type": "json_object" }` 可启用 JSON 模式。
seen	否	integer	测试阶段功能。指定种子（Seed）以尝试实现确定性输出。

4. 响应参数 (Response Body)

参数名	类型	说明
id	string	此次请求的唯一标识符。
object	string	对象类型，通常为 `chat.completion`。
created	integer	请求创建的时间戳（秒）。
choices	array	回复选项列表。
├─ index	integer	该选项在列表中的索引。
├─ message	object	模型生成的具体消息。
│ ├─ role	string	角色，通常为 `assistant`。
│ └─ content	string	消息文本内容。
└─ finish_reason	string	停止生成的原因（如 `stop`, `length`, `tool_calls`）。
usage	object	令牌使用情况。
├─ prompt_tokens	integer	输入消耗的 Token 数。
├─ completion_tokens	integer	输出消耗的 Token 数。
└─ total_tokens	integer	总消耗 Token 数。

5. 示例 (Example)

请求示例

{
    "model": "gpt-4o",
    "messages": [
        {
            "role": "user",
            "content": "who are u?"
        }
    ],
    "n": 1,
    "max_tokens": 100,
    "temperature": 0.8,
    "stream": false
}

响应示例

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "\r
\r
Hello there, how may I assist you today?"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}

6. 常见问题解答 (FAQs)

Q: 为什么我设置了 response_format: { "type": "json_object" } 却报错？ A: 使用 JSON 模式时，你必须在 messages 中明确通过系统消息或用户消息指示模型生成 JSON（例如：“请以 JSON 格式回复”）。否则，模型可能会因为无法生成有效的 JSON 而卡住或报错。

Q: temperature 和 top_p 可以同时调整吗？ A: 技术上可以，但官方通常建议二选一。调整其中一个通常就能达到改变输出随机性的目的，同时调整两个可能导致生成结果难以预测。

Q: stream: true 时如何接收数据？ A: 当开启流式传输时，服务器会发送一系列 Server-Sent Events (SSE)。每个事件的数据部分是一个 JSON 对象，最后会以 data: [DONE] 结尾。你需要使用流式解析库（如 Python 的 response.iter_lines()）来逐行处理。

Q: 如何计算 Token 消耗？ A: 对于英文，1 个 Token 大约等于 4 个字符或 0.75 个单词；对于中文，1 个汉字可能对应 1-2 个 Token。最终消耗以响应体中的 usage 字段为准。

Q: 出现 finish_reason: "length" 是什么意思？ A: 这表示生成的内容超过了你在 max_tokens 中设置的限制，或者是达到了模型的上下文最大长度限制，导致内容被截断了。

Q: 接口支持函数调用（Function Calling）吗？ A: 支持。通过 tools 参数定义函数原型，模型会根据需求在 choices[0].message 中返回 tool_calls，而不是普通的 content。