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

​
佇列端點

您可以透過以下端點存取所有佇列功能：
端點方法描述
api.sunra.ai/v1/queue/{model-id}POST將請求新增至佇列
api.sunra.ai/v1/queue/requests/{request_id}/statusGET擷取請求的狀態
api.sunra.ai/v1/queue/requests/{request_id}/status/streamGET串流狀態直到完成
api.sunra.ai/v1/queue/requests/{request_id}GET擷取請求的回應
api.sunra.ai/v1/queue/requests/{request_id}/cancelPUT取消請求
例如，要使用 curl 提交請求並將其新增至佇列： 
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 的範例回應： 
{
  "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。這讓您能夠追蹤狀態、佇列位置，或在回應準備好後擷取回應。

​
端點使用

curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status

​
範例回應

當您的請求在佇列中時，您將會收到像這樣的​​回應： 
{
  "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：直接連結到您已完成的回應。

​
啟用日誌

日誌提供有關請求處理的見解。它們預設為停用，但可以使用查詢參數啟用： 
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status?logs=1
每個日誌項目都包含：
  • message：事件的描述。
  • level：嚴重性 (例如，INFO、ERROR)。
  • source：日誌的來源。
  • timestamp：日誌產生的時間。

​
即時監控

若需持續更新，請使用串流端點： 
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 查詢參數附加到提交端點： 
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 請求，包含以下標頭：
HeaderValue
Content-Typeapplication/json
User-AgentSunra-AI-Webhook/1.0
您的端點必須在 5 秒內回傳 2xx 狀態碼。請快速確認並將耗時操作交給背景任務處理 — 回應過慢會被視為失敗並觸發重試。

​
負載

成功事件： 
{
  "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 的具體內容因失敗類型而異 — 下例展示其中一種常見形式： 
{
  "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 與輪詢或串流端點結合使用。

​
取消請求

如果您的請求仍在佇列中，您可以使用以下指令取消它： 
curl -X PUT https://api.sunra.ai/v1/queue/requests/{request_id}/cancel

​
擷取回應

一旦您的請求狀態為 COMPLETED，請使用以下指令擷取回應： 
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}
此端點也提供日誌以供檢閱。

​
透過 Sunra Client 簡化整合

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

​
速率限制

為確保公平使用和系統穩定性，我們的 API 端點受到以下速率限制：
端點類型速率限制突發限制
提交至佇列10 請求/秒100 請求/分鐘
所有其他端點100 請求/秒1,800 請求/分鐘
如果您超過這些限制，您將收到 403 Forbidden 回應。我們建議實作具有指數退避的重試機制來處理這些情況。