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": "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 形式で提供されます。

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

リクエストがまだキューにある場合は、次のようにキャンセルできます。 
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 応答が返されます。これらのケースを処理するために、指数バックオフ付きの再試行メカニズムを実装することをお勧めします。