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 -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": "ジブリ風の海辺の町。カラフルな家、はためく洗濯物、窓辺で眠る猫たち。"}'
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 |
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 応答が返されます。これらのケースを処理するために、指数バックオフ付きの再試行メカニズムを実装することをお勧めします。
