# 文字與串流輸出

透過同一個對話端點使用一般回應或 SSE 串流。

## 基礎端點

向 `POST /v1/chat/completions` 傳入 `model` 與 `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 事件。

只有模型與渠道支援時才要求串流用量回報。未收到最後的用量事件不代表沒有計費。

## 首字延遲與逾時

延遲包含網路、排隊、上游處理及代理緩衝。長上下文、推理與高併發可能增加等待。自己的閘道應關閉 SSE 緩衝並設定適當讀取逾時。瀏覽文件不會呼叫模型。

## 中斷與重試

客戶端斷線不保證上游停止，已產生的內容可能計費。逾時後先查紀錄，再決定是否重送，避免重複呼叫。