创建聊天补全 - DeepSeek v3.1 思考程度控制 (流式)

本接口用于创建与 DeepSeek v3.1 模型的聊天对话。支持流式输出（SSE）以及对模型深度思考能力（Thinking）的精细控制。

接口详情

接口状态: 已发布 (Released)
请求方式: 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 头部目前已禁用)

请求体 (Request Body)

Content-Type: application/json

参数名	必填	类型	描述
`model`	是	String	使用的模型的 ID。例如：`deepseek-v3-1-250821`
`messages`	是	Array of Objects	对话的消息列表。
? `role`	是	String	消息发送者的角色（如 `system`, `user`, `assistant`）。
? `content`	是	String	消息的具体内容。
`max_tokens`	否	Integer	限制一次请求中模型生成 completion 的最大 token 数。输入输出 token 的总长度受模型上下文限制。
`temperature`	否	Number	采样温度，介于 0 和 2 之间。较高的值（如 0.8）使输出更随机，较低的值（如 0.2）使输出更集中和确定。
`stream`	否	Boolean	如果设置为 `true`，将会以 SSE（server-sent events）的形式以流式发送消息增量。消息流以 `data: [DONE]` 结尾。
`stream_options`	否	Object	流式输出相关选项。只有在 `stream` 参数为 `true` 时，才可设置此参数。
? `include_usage`	否	Boolean	如果设置为 `true`，在流式消息最后的 `data: [DONE]` 之前会传输一个额外的块。此块上的 `usage` 字段显示整个请求的 token 使用统计信息。
`thinking`	否	Object	部分深度思考能力的模型支持通过此字段控制是否开启深度思考能力。
? `type`	否	String	`enabled`：强制开启深度思考能力。<br>`disabled`：强制关闭。<br>`auto`：模型自行判断。

请求示例

{
  "model": "deepseek-v3-1-250821",
  "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
  },
  "thinking": {
    "type": "enabled"
  }
}

响应体 (Response)

HTTP 状态码: 200 OK Content-Type: application/json

(注：当 stream: true 时，返回格式为 SSE 数据流，每个 data chunk 为以下结构的 JSON 字符串。以下为非流式或流式组装完成后的标准 JSON 结构)

字段名	类型	描述
`id`	String	请求的唯一标识符。
`object`	String	对象类型，通常为 `chat.completion` 或 `chat.completion.chunk`。
`created`	Integer	创建时间的时间戳（秒）。
`choices`	Array of Objects	模型生成的回复列表。
? `index`	Integer	该回复在 choices 列表中的索引。
? `message`	Object	生成的回复消息对象（流式请求中通常为 `delta`）。
? `role`	String	角色（通常为 `assistant`）。
? `content`	String	回复的具体内容。
? `finish_reason`	String	停止生成的原因（如 `stop`, `length`）。
`usage`	Object	Token 使用情况统计。
? `prompt_tokens`	Integer	提示词消耗的 Token 数量。
? `completion_tokens`	Integer	生成内容消耗的 Token 数量。
? `total_tokens`	Integer	消耗的总 Token 数量。

响应示例 (JSON)

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

常见问题解答 (FAQs)

Q1: 如何在流式 (SSE) 请求中获取 Token 消耗情况（Usage）？ A1: 您需要在请求体中将 stream 设置为 true，同时配置 stream_options: {"include_usage": true}。这样在 SSE 流结束标识 data: [DONE] 发送之前，服务器会额外推送一个数据块。该数据块的 choices 数组为空，但 usage 字段会包含完整的 Token 统计信息。

Q2: thinking 参数中的 enabled 和 auto 有什么区别？ A2:

enabled: 强制模型在返回最终答案前进行“深度思考（Chain of Thought）”，这通常会带来更高质量的推理结果，但可能会增加响应时间（首字延迟）和输出 Token 消耗。
auto: 将决策权交给模型，模型会根据您 messages 中的问题复杂度，自动判断是否需要进行深度思考。

Q3: 为什么请求返回了 401 Unauthorized 错误？ A3: 这通常是因为您的身份验证失败。请检查您的 Request Header 中的 Authorization 字段是否按照 Bearer {{YOUR_API_KEY}} 的格式正确填写，并确保您的 API Key 是有效且未过期的。

Q4: 开启 thinking 深度思考后，思考过程的内容会返回吗？ A4: 根据 OpenAI 兼容格式的标准实现，如果是流式输出，深度思考的内容可能会在特定的标识符（如 <think>...</think> 标签）内返回，或者通过特定的 chunk 字段返回。请在解析前端流式数据时，注意处理 content 中的思考过程内容，以便为用户展示“思考中”的 UI 效果。

Q5: 如果遇到 finish_reason: "length" 是什么意思？ A5: 这表示模型的输出达到了您设置的 max_tokens 限制，或者触碰到了模型本身最大上下文窗口的限制，导致回答被截断。如果回答不完整，您可以尝试调大 max_tokens 的值。