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

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

​
速率限制

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