> ## 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": "A Studio Ghibli-inspired seaside town with colorful houses, laundry flapping, and cats sleeping on windowsills."}'
```

`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"
}
```

## 取りうるステータス

リクエストは、次の 3 つの状態のいずれかになります。

* **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 は最終結果をその URL に `POST` するため、接続を維持したり定期的にポーリングしたりする必要はありません。

### Webhook の有効化

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 が返されます。

### Webhook が発火するタイミング

Sunra は **終端イベント時のみ** webhook を呼び出します:

* `succeeded` — リクエストが完了し、出力がペイロードに含まれます。
* `failed` — リクエストがエラーになり、エラーの詳細がペイロードに含まれます。

中間状態（`IN_QUEUE`、`IN_PROGRESS`）では 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` を含みます。`error` の正確な内容は失敗の種類によって異なります — 以下の例は一般的な形の 1 つです:

```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": "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 の配信は at-least-once です。エンドポイントがタイムアウト（5 秒）するか `2xx` 以外を返した場合、Sunra は指数バックオフで **最大 3 回** 再試行します（初期遅延 10 秒、最大 30 秒）。最終再試行後、失敗はログに記録され、それ以上の試行は行われません。

再試行により同じイベントが複数回配信される可能性があるため、ハンドラは冪等であるべきです — `id` フィールドをデデュプリケーションキーとして使用してください。

### ベストプラクティス

* HTTPS を使用し、トラフィックが想定したエンドポイントに到達していることを確認してください。
* 即座に `2xx` を返し、ペイロードは非同期で処理してください。
* 配信は at-least-once として扱い、`id` で重複排除してください。
* 終端イベントの前に進捗更新が必要な場合は、ポーリングまたはストリーミングのエンドポイントと組み合わせてください。

## リクエストのキャンセル

リクエストがまだキューにある場合は、次のようにキャンセルできます。

```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` 応答が返されます。これらのケースを処理するために、指数バックオフ付きの再試行メカニズムを実装することをお勧めします。