对于需要超过几秒钟的请求（在 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 客户端简化集成

Sunra 客户端自动化状态跟踪，简化使用 Sunra 功能的应用程序开发。

​
速率限制

为了确保公平使用和系统稳定性，我们的 API 端点受以下速率限制约束：
端点类型速率限制突发限制
提交到队列10 请求/秒100 请求/分钟
所有其他端点100 请求/秒1,800 请求/分钟
如果您超过这些限制，您将收到 403 Forbidden 响应。我们建议实施具有指数退避的重试机制来处理这些情况。