> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sunra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 队列

对于需要超过几秒钟的请求（在 AI 应用程序中很常见），我们开发了一个队列系统。该系统为您提供精细的控制来管理流量激增、在需要时取消请求，并监控您的请求在队列中的状态。它还消除了处理长时间运行的 HTTP 请求的需要。

## 队列端点

您可以通过以下端点访问所有队列功能：

| 端点                                                          | 方法   | 描述         |
| ----------------------------------------------------------- | ---- | ---------- |
| api.sunra.ai/v1/queue/\{model-id}                           | POST | 将请求添加到队列   |
| api.sunra.ai/v1/queue/requests/\{request\_id}/status        | GET  | 检索请求的状态    |
| api.sunra.ai/v1/queue/requests/\{request\_id}/status/stream | GET  | 流式传输状态直到完成 |
| api.sunra.ai/v1/queue/requests/\{request\_id}               | GET  | 获取请求的响应    |
| api.sunra.ai/v1/queue/requests/\{request\_id}/cancel        | PUT  | 取消请求       |

例如，要使用 curl 提交请求并将其添加到队列：

```bash theme={null}
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`的示例响应：

```json theme={null}
{
  "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。这允许您跟踪状态、队列位置，或在准备就绪时检索响应。

### 端点使用

```bash theme={null}
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status
```

## 示例响应

当您的请求在队列中时，您将收到如下响应：

```json theme={null}
{
  "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`：您已完成响应的直接链接。

## 启用日志

日志提供请求处理的洞察。默认情况下它们被禁用，但可以使用查询参数启用：

```bash theme={null}
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status?logs=1
```

每个日志条目包括：

* `message`：事件描述。
* `level`：严重程度（例如，INFO、ERROR）。
* `source`：日志来源。
* `timestamp`：生成日志的时间。

## 实时监控

要获得持续更新，请使用流式端点：

```bash theme={null}
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` 查询参数附加到提交端点：

```bash theme={null}
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` 请求，包含以下请求头：

| Header         | Value                  |
| -------------- | ---------------------- |
| `Content-Type` | `application/json`     |
| `User-Agent`   | `Sunra-AI-Webhook/1.0` |

您的端点必须在 5 秒内返回 `2xx` 状态码。请快速确认并将耗时操作放到后台任务中处理 — 响应过慢会被视为失败并触发重试。

### 负载

成功事件：

```json theme={null}
{
  "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`。`code` 能告诉你重试是否有意义——完整列表与重试指引见 [Prediction 失败代码](/zh-Hans/platform/errors#prediction-失败代码)：

```json theme={null}
{
  "id": "pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "object": "prediction",
  "model": "black-forest-labs/flux-1.1-pro",
  "model_endpoint": "text-to-image",
  "status": "failed",
  "input": {
    "prompt": "一个吉卜力风格的海边小镇..."
  },
  "error": {
    "code": "unsafe_content",
    "message": "The prediction may contain sensitive or restricted content and has been suppressed. Please revise your input."
  },
  "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` 时存在。包含机器可读的 `code` 与人类可读的 `message`——见 [Prediction 失败代码](/zh-Hans/platform/errors#prediction-失败代码)。 |
| `created_at`     | 请求创建时的 ISO 8601 时间戳。                                                                                           |
| `completed_at`   | 请求达到最终状态时的 ISO 8601 时间戳。                                                                                       |

### 重试机制

Webhook 投递保证至少一次。如果您的端点超时（5 秒）或返回非 `2xx` 状态，Sunra 会进行**最多 3 次**指数退避重试，初始延迟 10 秒，最大不超过 30 秒。最后一次重试失败后，会记录失败信息且不再尝试。

由于重试可能多次投递同一事件，请确保您的处理程序是幂等的 — 使用 `id` 字段作为去重键。

### 最佳实践

* 使用 HTTPS 并验证流量确实来自您预期的端点。
* 立即返回 `2xx`，将负载放到异步流程中处理。
* 将投递视为至少一次，并按 `id` 去重。
* 如果在最终事件之前还需要进度更新，请将 webhook 与轮询或流式端点结合使用。

## 取消请求

如果您的请求仍在队列中，您可以取消它：

```bash theme={null}
curl -X PUT https://api.sunra.ai/v1/queue/requests/{request_id}/cancel
```

## 检索响应

一旦您的请求为 `COMPLETED`，使用以下方式检索响应：

```bash theme={null}
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}
```

此端点还提供日志供审查。

## 使用 Sunra 客户端简化集成

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

## 速率限制

为了确保公平使用和系统稳定性，我们的 API 端点受以下速率限制约束：

| 端点类型       | 速率限制     | 突发限制        |
| :--------- | :------- | :---------- |
| **提交到队列**  | 10 请求/秒  | 100 请求/分钟   |
| **所有其他端点** | 100 请求/秒 | 1,800 请求/分钟 |

如果您超过这些限制，您将收到 `403 Forbidden` 响应。我们建议实施具有指数退避的重试机制来处理这些情况。