> ## Documentation Index
> Fetch the complete documentation index at: https://docs.geeknow.top/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat Completions（流式）

> 使用 OpenAI Chat Completions 兼容格式发起对话，并显式开启 SSE 流式返回。

# Chat Completions（流式）

使用统一对话格式调用 OpenAI、Claude、Gemini、DeepSeek、Qwen 等上游模型。本页展示流式写法，适合需要边生成边展示的聊天、Agent 和长文本生成场景。

<Info>
  如果未传 `stream`，接口默认按非流式返回。若希望固定获得流式响应，请显式传入 `"stream": true`。
</Info>

## 请求体

<ParamField body="model" type="string" required>
  模型名称。可通过 [模型列表](./models) 查询当前 API Key 可用模型。
</ParamField>

<ParamField body="messages" type="array<object>" required>
  按时间顺序排列的对话消息。常见角色为 `system`、`user`、`assistant`、`tool`。
</ParamField>

<ParamField body="messages[].content" type="string | array" required>
  消息内容。字符串表示纯文本；数组表示多模态内容，支持 `text`、`image_url`、`input_audio`、`file`、`video_url`。
</ParamField>

<ParamField body="stream" type="boolean" required>
  设为 `true` 后响应为 `text/event-stream`，每个片段以 `data:` 推送，结束时返回 `data: [DONE]`。
</ParamField>

<ParamField body="stream_options.include_usage" type="boolean">
  在流式最后一条消息中携带 token 用量统计。仅部分上游模型支持。
</ParamField>

<ParamField body="max_tokens" type="integer">
  限制最大生成 token 数。部分推理模型建议改用 `max_completion_tokens`。
</ParamField>

<ParamField body="max_completion_tokens" type="integer">
  限制最大补全 token 数，包含推理 token。适合支持 reasoning 的模型。
</ParamField>

<ParamField body="temperature" type="number">
  采样温度，常用范围 `0` 到 `2`。较低值更稳定，较高值更多样。
</ParamField>

<ParamField body="top_p" type="number">
  核采样参数，常用范围 `0` 到 `1`。通常不建议同时大幅调整 `temperature` 和 `top_p`。
</ParamField>

<ParamField body="tools" type="array<object>">
  函数调用工具列表，格式兼容 OpenAI `tools`。
</ParamField>

<ParamField body="tool_choice" type="string | object">
  控制模型是否调用工具。常见值为 `auto`、`none`、`required`，也可指定某个函数。
</ParamField>

<ParamField body="response_format" type="object">
  指定输出格式，例如 `{ "type": "json_object" }` 或 `json_schema`。
</ParamField>

<ParamField body="reasoning_effort" type="string">
  推理强度。常见值包括 `none`、`minimal`、`low`、`medium`、`high`、`xhigh`；是否生效取决于模型。高强度不一定更好，建议按业务评测选择。
</ParamField>

## 请求示例

<RequestExample>
  ```bash theme={null}
  curl -N -X POST https://www.geeknow.top/v1/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-5.5",
      "messages": [
        { "role": "system", "content": "你是一个简洁的技术助手。" },
        { "role": "user", "content": "用三点说明 API 网关的作用。" }
      ],
      "stream": true,
      "stream_options": {
        "include_usage": true
      }
    }'
  ```
</RequestExample>

### 多模态流式

图片 URL 需要能被上游模型公网下载；本地图片请先上传图床。base64 图片可使用 `data:image/png;base64,...` 形式放在 `image_url.url`。

```bash theme={null}
curl -N -X POST https://www.geeknow.top/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "概括这张图表的主要结论。" },
          { "type": "image_url", "image_url": { "url": "https://YOUR_IMAGE_HOST/path/chart.png", "detail": "high" } }
        ]
      }
    ],
    "stream": true
  }'
```

## 响应示例

<ResponseExample>
  ```text 200 theme={null}
  data: {"id":"chatcmpl_abc123","object":"chat.completion.chunk","created":1735689600,"model":"gpt-5.5","choices":[{"index":0,"delta":{"role":"assistant","content":"API"},"finish_reason":null}]}

  data: {"id":"chatcmpl_abc123","object":"chat.completion.chunk","created":1735689600,"model":"gpt-5.5","choices":[{"index":0,"delta":{"content":" 网关"},"finish_reason":null}]}

  data: {"id":"chatcmpl_abc123","object":"chat.completion.chunk","created":1735689600,"model":"gpt-5.5","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":26,"completion_tokens":38,"total_tokens":64}}

  data: [DONE]
  ```

  ```json 400 theme={null}
  {
    "error": {
      "message": "field model is required",
      "type": "invalid_request_error",
      "param": "",
      "code": "invalid_request"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "message": "Invalid API key provided",
      "type": "invalid_request_error",
      "param": "",
      "code": "invalid_api_key"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "message": "用户额度不足",
      "type": "new_api_error",
      "param": "",
      "code": "insufficient_user_quota"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "message": "当前请求频率过高，请稍后再试",
      "type": "new_api_error",
      "param": "",
      "code": "too_many_requests"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "message": "bad response body",
      "type": "new_api_error",
      "param": "",
      "code": "bad_response_body"
    }
  }
  ```
</ResponseExample>

## 响应字段

<ResponseField name="id" type="string">
  本次生成的响应 ID。
</ResponseField>

<ResponseField name="object" type="string">
  流式响应固定为 `chat.completion.chunk`。
</ResponseField>

<ResponseField name="choices[].delta" type="object">
  增量内容。可能包含 `role`、`content`、`reasoning_content` 或 `tool_calls`。
</ResponseField>

<ResponseField name="choices[].finish_reason" type="string">
  结束原因，常见值为 `stop`、`length`、`tool_calls`。
</ResponseField>

<ResponseField name="usage" type="object">
  用量统计。只有上游返回用量且启用 `stream_options.include_usage` 时才一定出现。
</ResponseField>

## 相关接口

* [Chat Completions（非流式）](./chat-completions-non-stream)
* [OpenAI Responses 接口](./openai-responses)
* [模型列表](./models)