> For the complete documentation index, see [llms.txt](https://docs.apismart.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/hui-ying-mo-shi.md).

# 回應模式

串流可讓您的應用程式在模型產生回應時，以小片段接收生成的文字，而不必等待完整結果。

這對聊天介面、助理，以及其他即時顯示文字的應用程式很有用。

串流適用於使用 [**Chat Completions API**](/documentation/zh-tw/api-zhi-nan/liao-tian-wan-cheng-api.md)。影片生成使用獨立的非同步任務工作流程。

***

### 啟用串流

若要請求串流回應，請加入：

```json
{
  "stream": true
}
```

範例請求本文：

```json
{
  "model": "YOUR_MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": "用一句話解釋 ApiSmart。"
    }
  ],
  "stream": true
}
```

> ⚠️ **重要：** 串流支援會因模型而異。請確認所選模型支援 `stream: true` 中的 **程式碼範例**.

***

### 傳送串流請求

cURL 範例：

```bash
curl https://gw.apismart.ai/v1/chat/completions \\
  -H "Authorization: Bearer $APISMART_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "用一句話解釋 ApiSmart。"
      }
    ],
    "stream": true
  }'
```

替換 `YOUR_MODEL_ID` 替換為所選模型詳細資料頁面上顯示的精確模型 ID。

***

### Python 範例

以下範例會逐步讀取回應：

```python
import os
import requests

api_key = os.getenv("APISMART_API_KEY")

if not api_key:
    raise RuntimeError("未設定 APISMART_API_KEY。")

搭配 requests.post(
    "https://gw.apismart.ai/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "model": "YOUR_MODEL_ID",
        "messages": [
            {
                "role": "user",
                "content": "請用一句話解釋 ApiSmart。",
            }
        ],
        "stream": True,
    },
    stream=True,
    timeout=120,
) as response:
    response.raise_for_status()

    for line in response.iter_lines(decode_unicode=True):
        if line:
            print(line)
```

實際的區塊結構可能因模型而異。請根據所選模型支援的回應格式來解析傳回的串流。

***

### 串流與非串流

| 模式  | 行為            |
| --- | ------------- |
| 非串流 | 在回傳之前會先等待完整回應 |
| 串流  | 逐步回傳生成的內容     |

當您希望使用者在文字可用時就看到生成內容，請使用串流。

對於背景處理或只需要最終結果的工作流程，標準的非串流請求可能更簡單。

***

### 重要注意事項

使用串流時：

* 保持連線開啟，直到串流結束。
* 在區塊到達時立即處理。
* 不要假設每個模型都會回傳相同的串流欄位。
* 在您的應用程式中處理連線中斷與 API 錯誤。
* 僅使用所選模型支援的參數。

串流不會改變模型 ID 或驗證方式。

***

### 🛠️ 常見問題

| 問題         | 檢查項目                   |
| ---------- | ---------------------- |
| **沒有串流輸出** | 確認該模型支援 `stream: true` |
| **驗證失敗**   | API 權杖狀態與 Bearer 標頭    |
| **找不到模型**  | 精確的模型 ID 與大小寫          |
| **連線提早關閉** | 用戶端逾時或網路中斷             |
| **無法解析區塊** | 所選模型實際回傳的回應格式          |

排除問題時，請檢查 [**使用紀錄與成本**](/documentation/zh-tw/api-shi-yong/shi-yong-ji-lu-yu-fei-yong.md) 中的相關請求，並在可用時儲存 **Request ID** 。

> 🔐 絕不要向支援提供你的完整 API Token。

***

### 🚀 下一步

繼續進行：

* [**Chat Completions API**](/documentation/zh-tw/api-zhi-nan/liao-tian-wan-cheng-api.md)
* [**選擇模型並尋找其模型 ID**](/documentation/zh-tw/mo-xing-yu-ding-jia/mo-xing-yu-mo-xing-id.md)
* [**API 基礎**](/documentation/zh-tw/api-zhi-nan/api-ji-chu.md)
* [**使用紀錄與成本**](/documentation/zh-tw/api-shi-yong/shi-yong-ji-lu-yu-fei-yong.md)