對於需要幾秒鐘以上時間的請求，這在 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 格式提供即時狀態更新，直到請求完成。

​
取消請求

如果您的請求仍在佇列中，您可以使用以下指令取消它： 
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 回應。我們建議實作具有指數退避的重試機制來處理這些情況。