队列端点
您可以通过以下端点访问所有队列功能：
例如，要使用 curl 提交请求并将其添加到队列：
request_id的示例响应：
request_id 并提供检查状态、取消或检索响应的 URL，简化您的工作流程而无需额外的端点开发。
请求状态
要监控请求的进度，请使用提供的端点和您的唯一请求 ID。这允许您跟踪状态、队列位置，或在准备就绪时检索响应。端点使用
示例响应
当您的请求在队列中时，您将收到如下响应：可能的状态
您的请求可以处于三种状态之一：-
IN_QUEUE：表示请求正在等待处理。
queue_position：显示您在队列中的位置。response_url：处理完成后检索响应的 URL。
-
IN_PROGRESS：请求当前正在处理中。
logs：详细日志（如果启用）显示处理步骤。response_url：最终响应将可用的位置。
-
COMPLETED：处理已完成。
logs：详细说明整个过程的日志。response_url：您已完成响应的直接链接。success：prediction 产出了输出时为true，失败时为false。error：success为false时是失败对象，否则为null。它与其他各通道发布的是同一个对象——见 Prediction 失败代码；若你在 2026 年 8 月 17 日之前完成对接，另见迁移说明。
启用日志
日志提供请求处理的洞察。默认情况下它们被禁用，但可以使用查询参数启用：message：事件描述。level：严重程度（例如，INFO、ERROR）。source：日志来源。timestamp：生成日志的时间。
实时监控
要获得持续更新，请使用流式端点：text/event-stream 格式的实时状态更新：第一个事件立即发送，之后每 2 秒发送一次。prediction 到达最终状态（COMPLETED——涵盖成功与失败两种情形——或 CANCELED）后，会发送最后一个事件然后服务端关闭连接；它不会反复重发终态事件。
Webhooks
如果您不想轮询，可以在提交请求时传入webhook 查询参数。当请求达到最终状态时，Sunra 会将最终结果 POST 到该 URL，无需保持长连接或定时轮询。
启用 Webhooks
将经过 URL 编码的webhook 查询参数附加到提交端点：
https%3A%2F%2F...），并确保 Sunra 可以访问到该地址；强烈建议使用 HTTPS。提交响应保持不变 — 您仍会收到 request_id 以及相同的状态/取消/响应 URL。
触发时机
Sunra 仅在最终事件时调用您的 webhook：succeeded— 请求已完成，输出包含在负载中。failed— 请求出错，错误详情包含在负载中。
IN_QUEUE、IN_PROGRESS）不会触发 webhook。如果您还需要进度更新，请将 webhook 与上文的流式或轮询端点结合使用。
请求格式
Sunra 将向您的 webhook URL 发送POST 请求，包含以下请求头：
您的端点必须在 5 秒内返回
2xx 状态码。请快速确认并将耗时操作放到后台任务中处理 — 响应过慢会被视为失败并触发重试。
负载
成功事件：output 替换为 error。用 retryable 决定要不要重试，用 reason 判断具体原因——完整词表见 Prediction 失败代码。retryable 恒定存在；reason 在上游给出具体原因时存在。两者都是开放集合，请容忍你不认识的值：
重试机制
Webhook 投递保证至少一次。您的端点有 5 秒时间响应；超时或返回非2xx 状态都算失败。Sunra 最多重试 3 次，前后跨度约两分钟——大致是 10–40 秒、30 秒、60 秒的间隔。（计算出的退避延迟每次翻倍、最高 30 秒，但重试只会被每 30 秒跑一次的调度器捡起，这才是看到的间隔不是干净的 10/20/30 秒的原因。）第三次重试失败后，会记录失败信息且不再尝试。
由于重试可能多次投递同一事件，请确保您的处理程序是幂等的 — 使用 id 字段作为去重键。
最佳实践
- 使用 HTTPS 并验证流量确实来自您预期的端点。
- 立即返回
2xx，将负载放到异步流程中处理。 - 将投递视为至少一次，并按
id去重。 - 如果在最终事件之前还需要进度更新，请将 webhook 与轮询或流式端点结合使用。
取消请求
如果您的请求仍在队列中，您可以取消它：检索响应
一旦您的请求为COMPLETED，使用以下方式检索响应：
空 Request ID
{request_id} 路径段为空——例如末尾或重复的斜杠、整段被省略，像 GET /v1/queue/requests//status、GET /v1/queue/requests/status（斜杠被合并）或裸的 GET /v1/queue/requests/——会在任何查找发生之前就被拒绝：
400 request_id_missing 覆盖所有带 request_id 的队列路由——/status、/status/stream、/cancel，以及裸的 result 端点——message 会指明你本来想调用的具体路由。这通常是复制代码片段里 $REQUEST_ID 变量没有被赋值的症状；一个格式正确但根本不存在的 id 是另一种失败（404，PREDICTION_NOT_FOUND——见API 请求错误）。
使用 Sunra 客户端简化集成
Sunra 客户端自动化状态跟踪，简化使用 Sunra 功能的应用程序开发。速率限制
为了确保公平使用和系统稳定性，我们的 API 端点受以下速率限制约束：
如果您超过这些限制，网关会返回
429 Too Many Requests（不是 403），并带上描述命中了哪个限制的响应头：
429 响应正在加入 JSON 错误体和 Retry-After 响应头（追踪单为 SUNRA-2741），目前尚未上线；在此之前，请只把状态码和上述 x-ratelimit-* 响应头当作可靠信号。x-ratelimit-reset（如可用）来安排重试时机，而不是立即重试。