创建聊天补全 (非流式)

该接口用于给定一个提示（Prompt），由模型返回一个或多个预测的补全结果。非流式接口会在生成完整响应后一次性返回结果。

接口地址: https://api.codingplanx.ai/v1/chat/completions
请求方法: POST
内容类型: application/json

请求参数

请求头 (Headers)

参数名	类型	必选	示例值	说明
Content-Type	string	是	`application/json`	请求体格式
Accept	string	是	`application/json`	响应体格式
Authorization	string	否	`Bearer {{YOUR_API_KEY}}`	身份验证令牌

请求体 (Body)

参数名	类型	必选	默认值	说明
model	string	是	-	要使用的模型 ID（如 `gpt-4o`, `gpt-3.5-turbo`）。
messages	array	是	-	对话消息列表。每个对象包含 `role` (system/user/assistant) 和 `content`。
temperature	number	否	1	采样温度 (0-2)。越高越随机，越低越确定。
top_p	number	否	1	核采样。仅考虑概率质量前 top_p 的标记。建议与 temperature 二选一调整。
n	integer	否	1	为每条输入消息生成的补全选择数量。
stream	boolean	否	false	是否流式传输。此处应设为 `false`。
stop	string/array	否	null	API 停止生成标记的阈值序列（最多4个）。
max_tokens	integer	否	inf	生成的最大标记数，受模型上下文长度限制。
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	否	-	模型可以调用的工具列表（目前仅支持 function）。
tool_choice	string/obj	否	auto	控制模型调用哪个函数（none/auto/指定函数）。

响应参数

响应体 (Response Body)

参数名	类型	说明
id	string	该次请求的唯一标识符。
object	string	对象类型，固定为 `chat.completion`。
created	integer	Unix 时间戳（秒）。
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 数。

示例

请求示例 (cURL)

curl --location --request POST 'https://api.codingplanx.ai/v1/chat/completions' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": "你好，请自我介绍一下。"
    }
  ],
  "max_tokens": 1000
}'

响应示例

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "你好！我是由 CodingPlanX 提供的 AI 助手，很高兴为你服务。"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 15,
        "completion_tokens": 25,
        "total_tokens": 40
    }
}

FAQs (常见问题解答)

Q1: 如何启用 JSON 模式？ A1: 在请求体中设置 "response_format": { "type": "json_object" }。注意： 当使用 JSON 模式时，你必须在 system 或 user 消息中明确指示模型输出 JSON，否则模型可能会产生无限循环的空白内容。

Q2: temperature 和 top_p 应该如何选择？ A2: 我们通常建议只修改其中一个。如果你需要模型更具创造性，可以调高 temperature (如 0.8)；如果你需要模型更严谨、回答更固定，可以调低它 (如 0.2)。

Q3: 为什么 finish_reason 是 length？ A3: 这表示生成的回复因为达到了你设置的 max_tokens 限制或者超过了模型的最大上下文长度而被截断。

Q4: 什么是 Token？ A4: Token 是模型处理文本的基本单位。对于中文，一个汉字大约等于 1~2 个 Token。API 的计费和上下文限制都是基于 Token 数量的。

Q5: presence_penalty 和 frequency_penalty 有什么区别？ A5: presence_penalty 关注的是“谈论新话题”，即只要词汇出现过就惩罚；frequency_penalty 关注的是“词汇重复次数”，即词汇出现次数越多惩罚越重。

Q6: 如果我想获取实时生成的文字效果，该怎么做？ A6: 请将 stream 参数设置为 true。注意，流式传输的响应格式与本篇文档（非流式）不同，它是基于 Server-Sent Events (SSE) 的。