> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sunra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 佇列

對於需要幾秒鐘以上時間的請求，這在 AI 應用中很常見，我們開發了一個佇列系統。這個系統讓您可以精細控制以管理流量高峰、在需要時取消請求，以及監控您在佇列中的請求狀態。它也消除了處理長時間執行的 HTTP 請求的需要。

## 佇列端點

您可以透過以下端點存取所有佇列功能：

| 端點                                                          | 方法   | 描述       |
| ----------------------------------------------------------- | ---- | -------- |
| api.sunra.ai/v1/queue/\{model-id}                           | POST | 將請求新增至佇列 |
| api.sunra.ai/v1/queue/requests/\{request\_id}/status        | GET  | 擷取請求的狀態  |
| api.sunra.ai/v1/queue/requests/\{request\_id}/status/stream | GET  | 串流狀態直到完成 |
| api.sunra.ai/v1/queue/requests/\{request\_id}               | GET  | 擷取請求的回應  |
| api.sunra.ai/v1/queue/requests/\{request\_id}/cancel        | PUT  | 取消請求     |

例如，要使用 curl 提交請求並將其新增至佇列：

```bash theme={null}
curl -X POST \
  https://api.sunra.ai/v1/queue/black-forest-labs/flux-1.1-pro/text-to-image \
  -H "Authorization: Key $SUNRA_KEY" \
  -d '{"prompt": "一個受吉卜力工作室啟發的海濱小鎮，有著彩色的房子、飄揚的衣物和睡在窗台上的貓。"}'
```

以下是包含 `request_id` 的範例回應：

```json theme={null}
{
  "request_id": "pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "response_url": "https://api.sunra.ai/v1/queue/requests/pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "status_url": "https://api.sunra.ai/v1/queue/requests/pd_vXW7VwPN2MbTwT8bzpWrYU5Y/status",
  "cancel_url": "https://api.sunra.ai/v1/queue/requests/pd_vXW7VwPN2MbTwT8bzpWrYU5Y/cancel"
}
```

承載中包含 `request_id`，並提供用於檢查狀態、取消或擷取回應的 URL，簡化您的工作流程而無需額外的端點開發。

## 請求狀態

若要監控您的請求進度，請使用提供的端點搭配您唯一的請求 ID。這讓您能夠追蹤狀態、佇列位置，或在回應準備好後擷取回應。

### 端點使用

```bash theme={null}
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status
```

## 範例回應

當您的請求在佇列中時，您將會收到像這樣的​​回應：

```json theme={null}
{
  "status": "IN_QUEUE",
  "metrics": {},
  "queue_position": 0,
  "response_url": "https://api.sunra.ai/v1/queue/requests/pd_hvTNHJPSZj4KgtzytfTGsySf",
  "status_url": "https://api.sunra.ai/v1/queue/requests/pd_hvTNHJPSZj4KgtzytfTGsySf/status",
  "cancel_url": "https://api.sunra.ai/v1/queue/requests/pd_hvTNHJPSZj4KgtzytfTGsySf/cancel"
}
```

## 可能的狀態

您的請求可以是以下三種狀態之一：

* **IN\_QUEUE**：表示請求正在等待處理。
  * `queue_position`：顯示您在佇列中的位置。
  * `response_url`：處理完成後擷取回應的 URL。

* **IN\_PROGRESS**：請求目前正在處理中。
  * `logs`：詳細的日誌 (如果啟用) 顯示處理步驟。
  * `response_url`：最終回應將可用的位置。

* **COMPLETED**：處理已完成。
  * `logs`：詳細說明整個過程的日誌。
  * `response_url`：直接連結到您已完成的回應。

## 啟用日誌

日誌提供有關請求處理的見解。它們預設為停用，但可以使用查詢參數啟用：

```bash theme={null}
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status?logs=1
```

每個日誌項目都包含：

* `message`：事件的描述。
* `level`：嚴重性 (例如，INFO、ERROR)。
* `source`：日誌的來源。
* `timestamp`：日誌產生的時間。

## 即時監控

若需持續更新，請使用串流端點：

```bash theme={null}
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status/stream
```

這會以 `text/event-stream` 格式提供即時狀態更新，直到請求完成。

## Webhooks

如果您不想輪詢，可以在提交請求時傳入 `webhook` 查詢參數。當請求達到最終狀態時，Sunra 會將最終結果 `POST` 到該 URL，無需保持長連接或定時輪詢。

### 啟用 Webhooks

將經過 URL 編碼的 `webhook` 查詢參數附加到提交端點：

```bash theme={null}
curl -X POST \
  "https://api.sunra.ai/v1/queue/black-forest-labs/flux-1.1-pro/text-to-image?webhook=https%3A%2F%2Fexample.com%2Fsunra-webhook" \
  -H "Authorization: Key $SUNRA_KEY" \
  -d '{"prompt": "一個吉卜力風格的海邊小鎮，有彩色房屋，晾衣繩飄揚，貓咪在窗台上睡覺。"}'
```

Webhook URL 需經過 URL 編碼（例如 `https%3A%2F%2F...`），並確保 Sunra 能夠存取該位址；強烈建議使用 HTTPS。提交回應保持不變 — 您仍會收到 `request_id` 以及相同的狀態/取消/回應 URL。

### 觸發時機

Sunra 僅在**最終事件**時呼叫您的 webhook：

* `succeeded` — 請求已完成，輸出包含在負載中。
* `failed` — 請求發生錯誤，錯誤詳情包含在負載中。

中間狀態（`IN_QUEUE`、`IN_PROGRESS`）**不會**觸發 webhook。如果您還需要進度更新，請將 webhook 與上文的串流或輪詢端點結合使用。

### 請求格式

Sunra 將向您的 webhook URL 發送 `POST` 請求，包含以下標頭：

| Header         | Value                  |
| -------------- | ---------------------- |
| `Content-Type` | `application/json`     |
| `User-Agent`   | `Sunra-AI-Webhook/1.0` |

您的端點必須在 5 秒內回傳 `2xx` 狀態碼。請快速確認並將耗時操作交給背景任務處理 — 回應過慢會被視為失敗並觸發重試。

### 負載

成功事件：

```json theme={null}
{
  "id": "pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "object": "prediction",
  "model": "black-forest-labs/flux-1.1-pro",
  "model_endpoint": "text-to-image",
  "status": "succeeded",
  "input": {
    "prompt": "一個吉卜力風格的海邊小鎮..."
  },
  "output": {
    "images": [
      { "url": "https://..." }
    ]
  },
  "created_at": "2026-04-28T12:00:00.000Z",
  "completed_at": "2026-04-28T12:00:08.123Z"
}
```

失敗事件將 `output` 替換為 `error`。`error` 的具體內容因失敗類型而異 — 下例展示其中一種常見形式：

```json theme={null}
{
  "id": "pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "object": "prediction",
  "model": "black-forest-labs/flux-1.1-pro",
  "model_endpoint": "text-to-image",
  "status": "failed",
  "input": {
    "prompt": "一個吉卜力風格的海邊小鎮..."
  },
  "error": {
    "code": "EXAMPLE_ERROR_CODE",
    "message": "可讀的錯誤訊息"
  },
  "created_at": "2026-04-28T12:00:00.000Z",
  "completed_at": "2026-04-28T12:00:08.123Z"
}
```

| 欄位               | 描述                                             |
| ---------------- | ---------------------------------------------- |
| `id`             | 提交時回傳的 `request_id`。可用於對重試進行去重。                |
| `object`         | 永遠為 `"prediction"`。                            |
| `model`          | 模型擁有者和名稱（例如 `black-forest-labs/flux-1.1-pro`）。 |
| `model_endpoint` | 端點名稱（例如 `text-to-image`）。                      |
| `status`         | `"succeeded"` 或 `"failed"`。                    |
| `input`          | 您提交的原始請求主體。                                    |
| `output`         | 在 `succeeded` 時存在。與結果端點回傳的回應主體相同。              |
| `error`          | 在 `failed` 時存在。描述失敗資訊的物件；具體結構因失敗類型而異。          |
| `created_at`     | 請求建立時的 ISO 8601 時間戳記。                          |
| `completed_at`   | 請求達到最終狀態時的 ISO 8601 時間戳記。                      |

### 重試機制

Webhook 投遞保證至少一次。如果您的端點逾時（5 秒）或回傳非 `2xx` 狀態，Sunra 會進行**最多 3 次**指數退避重試，初始延遲 10 秒，最大不超過 30 秒。最後一次重試失敗後，會記錄失敗資訊且不再嘗試。

由於重試可能多次投遞同一事件，請確保您的處理程序是冪等的 — 使用 `id` 欄位作為去重鍵。

### 最佳實踐

* 使用 HTTPS 並驗證流量確實來自您預期的端點。
* 立即回傳 `2xx`，將負載放到非同步流程中處理。
* 將投遞視為至少一次，並按 `id` 去重。
* 如果在最終事件之前還需要進度更新，請將 webhook 與輪詢或串流端點結合使用。

## 取消請求

如果您的請求仍在佇列中，您可以使用以下指令取消它：

```bash theme={null}
curl -X PUT https://api.sunra.ai/v1/queue/requests/{request_id}/cancel
```

## 擷取回應

一旦您的請求狀態為 `COMPLETED`，請使用以下指令擷取回應：

```bash theme={null}
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}
```

此端點也提供日誌以供檢閱。

## 透過 Sunra Client 簡化整合

Sunra 客戶端會自動追蹤狀態，簡化使用 Sunra 函數的應用程式開發。

## 速率限制

為確保公平使用和系統穩定性，我們的 API 端點受到以下速率限制：

| 端點類型       | 速率限制     | 突發限制        |
| :--------- | :------- | :---------- |
| **提交至佇列**  | 10 請求/秒  | 100 請求/分鐘   |
| **所有其他端點** | 100 請求/秒 | 1,800 請求/分鐘 |

如果您超過這些限制，您將收到 `403 Forbidden` 回應。我們建議實作具有指數退避的重試機制來處理這些情況。