创建聊天补全（流式）

接口描述

给定一个提示（Prompt），模型将返回一个或多个预测的补全对话内容。该接口同时支持标准返回与流式（SSE）返回，并且可以返回每个位置的替代标记的概率。

请求说明

请求方式：POST
请求地址：https://api.codingplanx.ai/v1/chat/completions

请求头 (Headers)

参数名称	必填	类型	示例	描述
`Content-Type`	是	string	`application/json`	数据格式
`Accept`	是	string	`application/json`	接收数据格式
`Authorization`	否*	string	`Bearer {{YOUR_API_KEY}}`	身份验证令牌（实际调用时通常为必填）
`X-Forwarded-Host`	否	string	`localhost:5173`	代理主机名（通常无需手动传递）

请求体 (Request Body)

参数名称	类型	必填	描述
`model`	string	是	要使用的模型 ID。有关兼容的模型列表，请参阅模型端点兼容性表。
`messages`	array	是	至今为止对话所包含的消息列表。包含 `role` 和 `content` 字段。
`tools`	array	是	模型可以调用的一组工具列表。目前只支持作为工具的函数。
`tool_choice`	object	是	控制模型调用哪个函数（如果有的话）。`none` 表示不调用，`auto` 表示自动选择，或强制调用特定函数。
`extra_body`	object	是	额外参数。包含 `enable_thinking`（boolean），设置是否开启思考模式（需模型支持）。
`temperature`	integer/float	否	采样温度，介于 0 和 2 之间。较高的值（如 0.8）输出更随机，较低的值（如 0.2）输出更集中和确定。建议修改此项或 `top_p`，但不要同时修改两者。
`top_p`	integer/float	否	核采样参数。0.1 意味着只考虑构成前 10% 概率质量的标记。建议修改此项或 `temperature`，但不要同时修改两者。
`n`	integer	否	为每个输入消息生成多少个聊天补全选择。默认为 1。
`stream`	boolean	否	是否开启流式输出。如果设置为 `true`，将以 Server-Sent Events (SSE) 的形式发送部分消息增量，并在 `data: [DONE]` 消息时终止流。
`stop`	string/array	否	API 将停止进一步生成标记的序列（最多 4 个）。默认为 null。
`max_tokens`	integer	否	在聊天补全中生成的最大标记数。输入和生成标记的总长度受模型上下文长度限制。
`presence_penalty`	number	否	-2.0 和 2.0 之间的数字。正值会根据文本中目前是否出现过新标记来惩罚它，增加模型谈论新主题的可能性。
`frequency_penalty`	number	否	-2.0 和 2.0 之间的数字。正值根据文本目前的存在频率惩罚新标记，降低模型重复相同内容的可能性。
`logit_bias`	object	否	修改指定标记出现在补全中的可能性。接受将标记 ID 映射到偏差值（-100 到 100）的 JSON 对象。
`user`	string	否	代表最终用户的唯一标识符，帮助监控和检测滥用行为。
`response_format`	object	否	指定模型输出的格式。设置为 `{ "type": "json_object" }` 启用 JSON 模式。注意：使用时必须在消息中指示模型生成 JSON，否则可能导致无限空白流。
`seen`	integer	否	设定种子 (Seed) 以进行确定性采样（Beta 功能）。

请求示例

{
  "model": "gpt-5-mini",
  "max_tokens": 1000,
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "你好"
    }
  ],
  "temperature": 1.0,
  "stream": true,
  "stream_options": {
    "include_usage": true
  }
}

响应说明

Content-Type: application/json (非流式) 或 text/event-stream (流式 stream: true 时)

响应参数 (非流式结构)

参数名称	类型	描述
`id`	string	聊天补全的唯一标识符。
`object`	string	对象类型，通常为 `chat.completion` 或 `chat.completion.chunk`。
`created`	integer	创建时间的时间戳（Unix 时间）。
`choices`	array	补全选择列表。
`choices[].index`	integer	在选择列表中的索引。
`choices[].message`	object	模型生成的消息对象，包含 `role` 和 `content`。在流式中为 `delta`。
`choices[].finish_reason`	string	停止生成的原因（如 `stop`、`length` 等）。
`usage`	object	API 令牌使用情况的统计信息。
`usage.prompt_tokens`	integer	提示（Prompt）消耗的 Token 数量。
`usage.completion_tokens`	integer	模型生成的 Token 数量。
`usage.total_tokens`	integer	本次请求消耗的总 Token 数量。

响应示例 (非流式 / 聚合流式结果)

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

(注：如果请求中指定了 stream: true，响应体将是由换行符分隔的 SSE 事件流，每行以 data: {...} 开头，最后以 data: [DONE] 结束。)

FAQs (常见问题解答)

Q1: 如何解析开启了 stream: true 的流式响应？ A: 当开启 stream: true 时，API 将通过 Server-Sent Events (SSE) 协议返回数据。客户端需要按行读取响应流，查找以 data: 前缀开头的字符串并解析为 JSON。请注意，数据流的最后一条消息固定为 data: [DONE]，标志着流的结束。解析时需过滤掉此结束标志。

Q2: 为什么我的 response_format 设置为 JSON 后，请求卡住或返回无限空白流？ A: 当您使用 { "type": "json_object" } 启用 JSON 模式时，必须在传入的 messages（通常在系统提示词 system prompt 中）明确指示模型“请输出 JSON 格式”。如果没有相关的文本提示，模型可能会陷入困境，生成无休止的空白字符，直到触发 max_tokens 限制。

Q3: temperature 和 top_p 参数可以同时调整吗？ A: 官方强烈建议不要同时调整这两个参数。两者都是用来控制模型输出随机性的机制。如果您想让输出更稳定、可预测，请降低 temperature 或缩小 top_p；如果想要更有创意的回答，则调高其中一个。同时修改两者会导致结果难以预测。

Q4: 参数中的 extra_body.enable_thinking 是什么作用？ A: 这是该接口的特殊扩展参数。当传递 {"enable_thinking": true} 时，如果后端当前使用的模型支持“思考模式（Thinking Mode/CoT）”（如某些推理增强大模型），模型将开启深度思考过程。如果模型不支持，该参数通常会被忽略。

Q5: 为什么响应中的 finish_reason 是 length 而不是 stop？ A: finish_reason 返回 length 表明模型尚未生成完整的回复，就被强制截断了。这通常是因为您的 max_tokens 参数设置得过小，或者您输入和生成的总 Token 数量超过了当前模型允许的最大上下文窗口限制。请尝试增大 max_tokens 值。