ガイド

クイックスタート

非同期タスクを作成し、ポーリング、完了、失敗、およびコールバックを処理します。

RunAPIは非同期の画像、動画、音声、および音楽生成にタスクを使用します。作成リクエストはすぐに返されます。その後、アプリケーションはタスクをポーリングするか、そのエンドポイントのAPIリファレンスに記載されているコールバックイベントを受信します。

タスクを作成する

カタログでモデルとエンドポイントを選択し、エンドポイントに必要な入力を送信します。この例ではFlux 2のテキストから画像へのタスクを開始します：

SHELL

curl -X POST "https://runapi.ai/api/v1/flux_2/text_to_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Idempotency-Key: 8c8ba3c9-0ce0-4bbd-a9a7-bf59ab639286" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-pro-text-to-image",
    "prompt": "A product photograph on a clean studio background"
  }'

受け付けられた非同期リクエストは、タスク識別子とともに 202 Accepted を返します：

JSON

{
  "id": "task_id",
  "status": "processing"
}

idをアプリケーションレコードと一緒に保存してください。これはポーリング、サポート、およびコールバックの照合に使用される安定した識別子です。

タスクの重複作成を防ぐ

タスク作成エンドポイントは、最大512文字の不透明な値を持つオプションのIdempotency-Keyヘッダーを受け付けます。論理タスクごとに1つの値を生成し、受け付けられたかどうかが確認できるまでリクエストと共に保持してください。

タイムアウトや接続障害によって結果が不明な場合は、同じキーを使用してまったく同じタスク作成リクエストを再試行してください。RunAPI は 2 回目のタスクを作成して課金する代わりに、元のタスクを返します。異なるタスク作成リクエストに同じキーを再利用すると 409 Conflict が返されます。意図的に新しいタスクを作成する場合は新しいキーを生成し、このキーとして X-Client-Request-Id を使用しないでください。

中断された同期リクエストを復旧する

低速の同期エンドポイントは通常、接続を開いたままにして、以前と同じ終端レスポンスを返します。既存の統合ではポーリングの変更は不要です。

意図的に短い接続予算を設定するには、Prefer: wait=Nを送信します。その明示的な予算の後もTaskがまだ実行中の場合、RunAPIは同じTaskのid、復元用の不透明なLocation URL、および推奨クエリ遅延のためのRetry-Afterを含む202 Acceptedを返します。結果URLを構築するのではなく、Locationを正確に追跡してください。完了したTask ResultはターミナルのHTTPステータス、許可されたヘッダー、コンテンツタイプ、およびボディを保持します。response.content_type（常にJSONとは限りません）に従ってresponse.bodyをデコードしてください。

タスクをポーリングする

同じエンドポイントパスにタスク識別子を追加します：

SHELL

curl "https://runapi.ai/api/v1/flux_2/text_to_image/task_id" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

statusがprocessingの間は続けてください。継続的なポーリングの代わりに、リクエスト間に制限付きバックオフを使用してください。タスクのステータスがcompletedまたはfailedになるとターミナル状態になります。

完了の処理

completed レスポンスにはタスクの id、終端 status、およびエンドポイント固有の結果フィールドが含まれます。必要な結果を保存し、ポーリングを停止します。すべてのメディアエンドポイントが同じフィールドを返すと仮定せず、正確な結果の形式についてはエンドポイントの API リファレンスを参照してください。

失敗の処理

failed レスポンスにはタスクの id、終端 status、および利用可能な場合は RunAPI が提供する error が含まれます。ポーリングを停止し、識別子とエラーを記録し、アプリケーションが障害を一時的なものと分類した場合のみ再試行します。再試行すると新しいタスク識別子が作成されます。

コールバックを受信する

RunAPI がそのエンドポイント向けに文書化されたコールバックイベントを送信するようにするには、作成リクエストに公開 HTTPS の callback_url を追加します：

JSON

{
  "model": "flux-2-pro-text-to-image",
  "prompt": "A product photograph on a clean studio background",
  "callback_url": "https://your-domain.com/webhooks/runapi"
}

各コールバックボディはエンドポイントのAPIリファレンスの1つのライフサイクルイベントに対応し、ポーリング専用の請求詳細は含まれません。ターミナルコールバックにはターミナルポーリングレスポンスと同じ結果フィールドが含まれます。一部のエンドポイントはprocessingコールバックも送信します。成功したHTTPレスポンスを迅速に返し、配信が遅延したりコールバックハンドラーが利用できない場合の調整のためにポーリングも利用可能な状態に維持してください。

コールバックシークレットの作成、署名の検証、リトライの安全な処理方法については、コールバックをお読みください。