> 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/yi-nan-pai-jie/yu-shi-yu-lian-xian-wen-ti.md).

# 逾時與連線問題

排解 ApiSmart 請求逾時、連線問題、暫時性服務錯誤，以及耗時較長的圖片與影片生成請求。

某些 ApiSmart 請求可能比一般 API 呼叫花更長時間，特別是圖片與影片生成。

如果請求逾時或回傳暫時性 `5xx` 錯誤，請先判斷問題是由於你的用戶端逾時、長時間執行的生成，還是暫時性的上游服務問題。

### ⏱️ 圖片請求逾時

圖片生成預設為同步。

當你呼叫：

```
POST /v1/images/generations
```

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

單張圖片通常需要約 **20–40 秒**。高解析度圖片、多張參考圖片或連續生成可能需要更久。

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

```
90 秒
```

使用稍長一些的值，例如 **120 秒** 可提供額外的緩衝。

> **重要：** 用戶端逾時不一定代表生成失敗。即使你的用戶端在接收結果前中斷，圖片仍可能完成並產生費用。

如果發生這種情況，請先檢查 [**生成媒體歷史記錄**](https://docs.apismart.ai/documentation/zh-tw/api-shi-yong-liang/sheng-cheng-mei-ti-li-shi.md) 或 [**使用記錄與成本**](https://docs.apismart.ai/documentation/zh-tw/api-shi-yong-liang/shi-yong-ji-lu-yu-cheng-ben.md) ，再立即再次送出相同請求。

### 🎬 影片請求不應等待完成

影片生成採用非同步任務流程。

先建立影片任務，再另外查詢其狀態。

```
POST /v1/video/tasks
        ↓
接收任務 ID
        ↓
GET /v1/video/tasks/{id}
```

在生成進行中時，任務可能回傳：

| 狀態          | 含義    |
| ----------- | ----- |
| `queued`    | 排隊中   |
| `running`   | 生成進行中 |
| `succeeded` | 生成完成  |
| `failed`    | 生成失敗  |
| `cancelled` | 任務已取消 |
| `expired`   | 任務已過期 |

在等待最終影片期間，不要保持原始影片建立請求開啟。

在狀態為 `queued` 或 `running`.

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

### 🔌 502 — 閘道或上游錯誤

A `502` 回應可能表示 ApiSmart 與上游模型服務或網路層之間出現暫時性問題。

可能的代碼包括：

```
proxy_error
BadGateway
```

這些錯誤可能是暫時性的。

請稍候片刻再重試，並使用指數退避，而不是立即連續送出請求。

### ⚠️ 503 — 服務暫時無法使用

A `503` 可能表示相依服務暫時無法使用。

可能的代碼包括：

| 代碼                                | 含義            |
| --------------------------------- | ------------- |
| `provider_not_available`          | 模型供應商暫時無法使用   |
| `quota_service_unavailable`       | 配額服務暫時無法使用    |
| `proxy_unavailable`               | 代理相依項目暫時無法使用  |
| `asset_owner_service_unavailable` | 資產擁有者服務暫時無法使用 |

如果回應提供 `Retry-After`，請在指示的時間過後再重試。

如果 `503` 是在切換模型後立即出現，也請確認模型 ID。ApiSmart 模型 ID 必須完全相符。

### ⌛ 504 — 閘道逾時

A `504 GatewayTimeout` 表示上游服務未在預期時間內回應。

這可能是暫時性的服務或網路層問題。

建議的處理方式是等待，並使用受控的指數退避重試。

例如：

```
1 秒 → 2 秒 → 4 秒 → 8 秒
```

請在合理次數後停止，而不要無限重試。

### 🔁 謹慎重試暫時性錯誤

針對如 `502`, `503`，以及 `504`這類暫時性連線或服務失敗，請使用受控重試。

良好的重試策略應該：

* 在各次嘗試之間等待
* 在多次失敗後增加延遲時間
* 遵循 `Retry-After` （若有提供）
* 設定最大重試次數
* 避免持續重試同一個請求

請不要將此重試策略自動套用到無效參數、驗證失敗或餘額不足。

完整的重試指南請參閱 [**HTTP 狀態碼與 API 錯誤**](https://docs.apismart.ai/documentation/zh-tw/yi-nan-pai-jie/http-zhuang-tai-ma-yu-api-cuo-wu.md).

### 🔎 請求已逾時，但你不確定發生了什麼

在再次送出相同請求之前，請先確認它是否可能已經完成。

對於圖片生成，請查看 [**生成媒體歷史記錄**](https://docs.apismart.ai/documentation/zh-tw/api-shi-yong-liang/sheng-cheng-mei-ti-li-shi.md) 以及 [**使用記錄與成本**](https://docs.apismart.ai/documentation/zh-tw/api-shi-yong-liang/shi-yong-ji-lu-yu-cheng-ben.md).

對於影片生成，請查詢：

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

使用任務建立時回傳的任務 ID。

這有助於避免不必要的重複生成與額外費用。

### ✅ 快速疑難排解清單

當請求逾時或連線中斷時，請先檢查端點：同步圖片生成請至少使用 90 秒逾時，影片任務請輪詢而不要等待完成，並且僅在受控退避下重試 `502`, `503`，或 `504` 。如果請求可能已經完成，請在再次送出前先檢查其任務狀態、媒體歷史或使用紀錄。

其他失敗情況請參閱 [**HTTP 狀態碼與 API 錯誤**](https://docs.apismart.ai/documentation/zh-tw/yi-nan-pai-jie/http-zhuang-tai-ma-yu-api-cuo-wu.md).

### ➡️ 下一步

[**HTTP 狀態碼與 API 錯誤**](https://docs.apismart.ai/documentation/zh-tw/yi-nan-pai-jie/http-zhuang-tai-ma-yu-api-cuo-wu.md) — 檢視所有 API 錯誤代碼\
[**圖片生成 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) — 了解非同步影片任務\
[**使用記錄與成本**](https://docs.apismart.ai/documentation/zh-tw/api-shi-yong-liang/shi-yong-ji-lu-yu-cheng-ben.md) — 調查請求活動與費用\
[**生成媒體歷史記錄**](https://docs.apismart.ai/documentation/zh-tw/api-shi-yong-liang/sheng-cheng-mei-ti-li-shi.md) — 檢查最近生成的媒體
