聊天补全 API 文档 (Chat Completions)

本接口用于给定一个提示（Prompt），模型将返回一个或多个预测的补全结果。您可以根据对话历史生成文本，并控制生成过程的随机性、长度和格式。

接口名称：列出模型 / 聊天补全
请求方法：GET (注：根据提供的数据定义)
请求地址：https://api.codingplanx.ai/v1/models
状态：已发布 (Released)

1. 请求参数

1.1 Header 参数

参数名	必选	类型	示例值	说明
Content-Type	是	String	`application/json`	接口请求体格式
Accept	是	String	`application/json`	接口响应格式
Authorization	否	String	`Bearer {{YOUR_API_KEY}}`	用于身份验证的 API 密钥

1.2 Body 参数

尽管原始定义为 GET，但根据业务逻辑，以下参数通常通过 JSON Body 传递。

参数名	类型	必选	默认值	描述
model	string	是	-	要使用的模型 ID。例如：`gpt-3.5-turbo`。
messages	array	是	-	至今为止对话所包含的消息列表。每条消息包含 `role` 和 `content`。
temperature	number	否	1	采样温度，介于 0 和 2 之间。值越高输出越随机。
top_p	number	否	1	核采样。0.1 表示只考虑构成前 10% 概率质量的标记。
n	integer	否	1	为每个输入生成多少个聊天补全选择。
stream	boolean	否	false	是否流式传输。设置为 true 时，将发送部分消息增量（SSE）。
stop	string/array	否	null	停止序列。模型在遇到这些字符时将停止生成。
max_tokens	integer	否	inf	生成的最大标记（Tokens）数。
presence_penalty	number	否	0	-2.0 到 2.0 之间的数字。正值增加模型谈论新主题的可能性。
frequency_penalty	number	否	0	-2.0 到 2.0 之间的数字。正值降低模型重复相同行的可能性。
logit_bias	object	否	null	修改指定标记出现在补全中的可能性。
user	string	否	-	代表最终用户的唯一标识符，帮助监控滥用。
response_format	object	否	-	指定模型输出格式，如 `{ "type": "json_object" }` 启用 JSON 模式。
tools	array	否	-	模型可以调用的工具列表（如函数）。
tool_choice	object	否	auto	控制模型调用哪个函数。

2. 响应参数

参数名	类型	说明
id	string	该次请求的唯一标识符。
object	string	对象类型，通常为 `chat.completion`。
created	integer	请求创建的时间戳（秒）。
choices	array	包含补全结果的列表。
├─ index	integer	该选择在列表中的索引。
├─ message	object	模型生成的具体消息。
│ ├─ role	string	角色，通常为 `assistant`。
│ └─ content	string	消息正文内容。
└─ finish_reason	string	停止原因，如 `stop` (正常停止) 或 `length` (达到最大长度)。
usage	object	令牌使用情况统计。
├─ prompt_tokens	integer	输入消耗的 Token 数。
├─ completion_tokens	integer	输出生成的 Token 数。
└─ total_tokens	integer	总消耗 Token 数。

3. 请求示例

成功请求示例

curl --location --request GET 'https://api.codingplanx.ai/v1/models' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
  "model": "gpt-3.5-turbo",
  "messages": [
    {
      "role": "user",
      "content": "Hello there, how may I assist you today?"
    }
  ],
  "temperature": 1,
  "top_p": 1,
  "n": 1,
  "stream": false,
  "user": "user-1234"
}'

成功响应示例

{
    "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
    }
}

4. FAQs (常见问题)

Q: 为什么文档里显示是 GET 方法，但看起来像是 POST 请求？ A: 在标准的 OpenAI 规范中，创建补全通常使用 POST 方法。但根据您提供的元数据，该接口被定义为 GET。请确保在调用时确认服务器端的实际配置。如果 GET 不生效，请尝试使用 POST。

Q: temperature 和 top_p 应该如何选择？ A: 我们建议只调整其中一个。如果你想要更精准、确定的回答，请降低 temperature（如 0.2）；如果你想要更多样化、创意的回答，可以提高它。

Q: 如何启用 JSON 模式？ A: 你需要在 response_format 中设置 { "type": "json_object" }，并且在 messages 中明确告知模型（System 或 User 消息）需要输出 JSON 格式，否则模型可能会产生解析错误或无限空白。

Q: 什么是 presence_penalty 和 frequency_penalty？ A:

presence_penalty（存在惩罚）：侧重于惩罚已经出现过的主题，鼓励模型谈论新话题。
frequency_penalty（频率惩罚）：侧重于惩罚重复出现的词汇，防止模型在短时间内重复同样的句子。

Q: 流式输出 (stream: true) 是如何工作的？ A: 开启流式后，API 会通过 Server-Sent Events (SSE) 逐字返回数据。每个数据块都是以 data: 开头的 JSON 字符串，最后以 data: [DONE] 结束。这对于长文本生成的实时展示非常有用。