キュー

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 を使用してリクエストを送信し、キューに追加するには、次のようにします。

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 を含むサンプル応答は次のとおりです。

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

取りうるステータス

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

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

Webhook の有効化

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

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 ステータスコードで応答する必要があります。素早く受領応答し、重い処理はバックグラウンドジョブにオフロードしてください — 応答が遅いと失敗とみなされ、再試行が発生します。

ペイロード

成功イベント:

{
  "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 つです:

{
  "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 で重複排除してください。
終端イベントの前に進捗更新が必要な場合は、ポーリングまたはストリーミングのエンドポイントと組み合わせてください。

リクエストのキャンセル

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

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

概要

Multimodal

LLM

クライアントライブラリ

キューエンドポイント

リクエストステータス

エンドポイントの使用法

応答の例

取りうるステータス

ログの有効化

リアルタイム監視

Webhooks

Webhook の有効化

Webhook が発火するタイミング

リクエスト形式

ペイロード

再試行の挙動

ベストプラクティス

リクエストのキャンセル

応答の取得

Sunra クライアントによる簡素化された統合

レート制限

​キューエンドポイント

​リクエストステータス

​エンドポイントの使用法

​応答の例

​取りうるステータス

​ログの有効化

​リアルタイム監視

​Webhooks

​Webhook の有効化

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

​リクエスト形式

​ペイロード

​再試行の挙動

​ベストプラクティス

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

​応答の取得

​Sunra クライアントによる簡素化された統合

​レート制限

キューエンドポイント

リクエストステータス

エンドポイントの使用法

応答の例

取りうるステータス

ログの有効化

リアルタイム監視

Webhooks

Webhook の有効化

Webhook が発火するタイミング

リクエスト形式

ペイロード

再試行の挙動

ベストプラクティス

リクエストのキャンセル

応答の取得

Sunra クライアントによる簡素化された統合

レート制限