# 文本与流式输出

用同一个对话接口接入普通响应和 SSE 流式输出。

## 基础接口

使用 `POST /v1/chat/completions`，至少传入 `model` 和 `messages`。`messages` 保存对话消息；多轮对话通常需要由客户端提交需要保留的历史。



```bash
curl 'https://api.xsopc.com/v1/chat/completions' \
  -H "Authorization: Bearer $XINGSUAN_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<JSON
{
  "model": "$XINGSUAN_MODEL",
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    }
  ]
}
JSON
```



## 参数与模型差异

| 字段 | 使用说明 |
| --- | --- |
| `model` | 使用平台公布的完整模型 ID |
| `messages` | 消息数组；图片等内容需要模型支持对应输入类型 |
| `stream` | 设置 `true` 请求流式输出 |
| `temperature` | 可选；支持情况和范围因模型而异 |
| `max_tokens` 等输出限制 | 仅使用该模型支持的字段，不要同时填写多个互相冲突的限制 |

推理内容、工具调用、结构化输出和额外参数并非所有模型都支持。请按模型详情选择，避免照搬其他模型的请求体。

## SSE 流式调用



```bash
curl -N 'https://api.xsopc.com/v1/chat/completions' \
  -H "Authorization: Bearer $XINGSUAN_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<JSON
{
  "model": "$XINGSUAN_MODEL",
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    }
  ],
  "stream": true
}
JSON
```



`curl -N` 关闭客户端输出缓冲。正常流式响应为 `text/event-stream`，数据按事件到达；客户端应处理事件边界、空增量、结束标记及错误，不要把每个网络数据块当作一条完整 JSON。

如果需要客户端显示 token 用量，只有模型和渠道支持时才使用对应的用量参数。没有收到最后一块用量，不代表请求没有计费。

## 首字延迟与超时

首字延迟包含客户端到平台的网络耗时、排队、上游推理及代理缓冲。长上下文、复杂推理和高并发通常需要更长时间；使用流式输出可在有内容时尽早展示。

自己的网关或反向代理应关闭 SSE 缓冲并设置适当的读取超时。文档站与模型请求独立，打开文档不会触发模型生成。

## 中断和重试

客户端断开不等于上游立即停止。已经生成的内容或已经完成的工作可能计入费用。网络超时后先检查调用记录，再决定是否重发，避免无条件重试造成重复调用。