> 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).

# 回應模式

了解 ApiSmart API 如何回傳結果，包括標準回應、串流輸出、同步圖片生成以及非同步影片任務。

ApiSmart API 會根據工作負載類型使用不同的回應模式。

文字請求可以返回完整回應，或逐步串流生成的內容。圖片生成預設為同步，也可以支援串流。影片生成使用非同步任務，因為生成完成可能需要更長時間。

了解這些回應模式有助於你為應用程式選擇正確的請求處理策略。

### 🔄 回應模式一覽

| API      | 預設模式  | 替代模式   |
| -------- | ----- | ------ |
| **聊天完成** | 標準回應  | 串流     |
| **圖片生成** | 同步回應  | SSE 串流 |
| **影片生成** | 非同步任務 | —      |

實作會因 API 而異，因此請始終遵循你所使用端點文件中記載的行為。

### 📄 標準回應

標準回應會等待模型完成處理請求，然後返回已完成的結果。

這是未啟用串流時，Chat Completions 的預設行為。

範例：

```bash
curl https://gw.apismart.ai/v1/chat/completions \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {
        "role": "user",
        "content": "用簡單的方式解釋 API 閘道。"
      }
    ]
  }'
```

標準回應適用於以下情況：

* 你希望一次收到完整結果
* 回應相對較短
* 你的應用程式不需要漸進式輸出
* 偏好更簡單的請求處理

如需請求參數和範例，請參閱 [**Chat Completions API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/liao-tian-bu-quan-api.md).

### 🌊 串流文字回應

Chat Completions 可以逐步返回生成內容，而不是等待完整回應。

啟用串流，設定：

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

範例：

```bash
curl https://gw.apismart.ai/v1/chat/completions \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {
        "role": "user",
        "content": "寫一個短篇故事。"
      }
    ],
    "stream": true
  }'
```

串流對以下情況很有幫助：

* 對話式應用程式
* 較長的文字生成
* 在生成時即顯示輸出的介面
* 提早接收部分輸出可改善使用者體驗的應用程式

如果不需要串流，請省略 `stream` 或使用預設回應行為。

如需完整請求格式，請參閱 [**Chat Completions API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/liao-tian-bu-quan-api.md).

### 🖼️ 同步圖片回應

圖片生成功能預設為同步。

當你送出請求至：

`POST /v1/images/generations`

連線會保持開啟，直到圖片生成完成並返回結果。

範例：

```bash
curl https://gw.apismart.ai/v1/images/generations \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0",
    "prompt": "日出時分的山村，水彩風格",
    "size": "2K"
  }'
```

圖片生成所需時間可能遠長於一般文字請求。

單張圖片通常大約需要 **20–40 秒**，而高解析度、多參考或順序生成請求可能需要更久。

請將用戶端逾時至少設定為：

`90 秒`

> 如果你的用戶端在回應返回前中斷連線，生成可能仍會完成並產生費用。

如需完整圖片請求參數，請參閱 [**圖片生成 API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/tu-pian-sheng-cheng-api.md).

### 🌊 串流圖片回應

支援的圖片生成工作流程也可以使用 SSE 串流返回結果。

透過以下方式啟用串流：

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

使用 curl 測試時，請使用 `-N` 以防止輸出緩衝：

```bash
curl https://gw.apismart.ai/v1/images/generations \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -N \
  -d '{
    "model": "doubao-seedream-5-0",
    "prompt": "建立一個極簡產品設計序列",
    "size": "2K",
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": {
      "max_images": 6
    },
    "stream": true
  }'
```

串流對可能產生多個圖片結果的生成工作流程特別有用。

如需支援的圖片參數與順序生成選項，請參閱 [**圖片生成 API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/tu-pian-sheng-cheng-api.md).

### 🎬 非同步影片任務

影片生成使用不同的回應模式。

ApiSmart 不會讓原始請求持續開啟直到影片完成，而是建立一個非同步任務。

典型流程如下：

1. 建立影片任務
2. 收到任務 ID
3. 查詢任務狀態
4. 在任務處理期間持續輪詢
5. 當任務成功後擷取結果

#### 步驟 1：建立任務

傳送：

`POST /v1/video/tasks`

範例：

```bash
curl https://gw.apismart.ai/v1/video/tasks \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0",
    "prompt": "夜晚的微型城市，火車穿梭於街道之間",
    "duration": 5,
    "size": "720p"
  }'
```

回應包含任務 ID。

#### 步驟 2：查詢任務

使用任務 ID 搭配：

`GET /v1/video/tasks/{id}`

範例：

```bash
curl https://gw.apismart.ai/v1/video/tasks/<task_id> \
  -H "Authorization: Bearer <your-api-key>"
```

#### 任務狀態

| 狀態          | 意義      |
| ----------- | ------- |
| `queued`    | 等待開始    |
| `running`   | 生成進行中   |
| `succeeded` | 生成已成功完成 |
| `failed`    | 生成失敗    |
| `cancelled` | 任務已取消   |
| `expired`   | 任務已過期   |

在任務處理期間持續輪詢 `queued` 或 `running`.

當任務達到 `succeeded`，回應可包含已生成的影片結果。

如需完整的影片工作流程和參數，請參閱 [**影片生成 API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/ying-pian-sheng-cheng-api.md).

### 🧩 選擇正確的回應模式

通常你不需要手動在所有回應模式之間做選擇。可用選項取決於你正在呼叫的 API。

請使用以下一般指引：

| 情境               | 建議模式  |
| ---------------- | ----- |
| 短文字生成            | 標準回應  |
| 互動式或較長的文字生成      | 串流    |
| 一般圖片生成           | 同步回應  |
| 需要漸進式輸出的支援多圖工作流程 | 圖片串流  |
| 影片生成             | 非同步任務 |

在建置使用多個 ApiSmart API 的應用程式時，應根據各端點的回應行為來處理，而不是假設所有模型都以相同方式返回結果。

### ⚠️ 逾時與長時間執行請求

不同的回應模式需要不同的逾時策略。

對於標準文字請求，請使用與預期生成長度相符的逾時時間。

對於同步圖片生成，請將用戶端逾時至少設定為 **90 秒**.

對於非同步影片生成，你的初始請求只會建立任務。之後應由應用程式另外查詢該任務，直到其進入最終狀態。

避免僅因生成時間比一般 API 呼叫更長，就將長時間執行的生成視為失敗請求。

### ➡️ 下一步

繼續以下內容：

* [**Chat Completions API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/liao-tian-bu-quan-api.md) — 傳送標準與串流文字請求
* [**圖片生成 API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/tu-pian-sheng-cheng-api.md) — 使用同步與串流圖片生成
* [**影片生成 API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/ying-pian-sheng-cheng-api.md) — 建立並查詢非同步影片任務
* [**API 基礎**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/api-ji-chu.md) — 檢視常見 API 約定
* [**HTTP 狀態碼與 API 錯誤**](https://docs.apismart.ai/documentation/zh-tw/yi-nan-pai-jie/http-zhuang-tai-ma-yu-api-cuo-wu.md) — 處理 API 錯誤與暫時性失敗
