コンテンツへスキップ
ガイド
ガイド

クイックスタート

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

Markdownを表示

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

メディア入力を送信する

Media Input Field は、メディア URL を含むリクエストフィールドです。名前が _url または _urls で終わるトップレベルのフィールド（例: image_url、image_urls）、video_list の各項目の url、kling_elements の各項目の element_input_urls、element_input_video_urls、element_input_audio_urls が該当します。callback_url は配信先エンドポイントであり、Media Input Field ではありません。各 Media Input Field の値には公開 HTTPS URL、または data:<mime>;base64,<data> 形式の data URI を指定できます。data URI 1 件あたりの上限は 10 MB です。RunAPI は各 data URI を 1 時間後に期限切れとなる一時的な File Upload として保存し、その File Upload を Task で使用します。保存できない data URI はエラーコード invalid_media_input とともに 422 を返します。

GPT Image の編集エンドポイントは、source_image_urls に HTTPS URL のみを受け付けます。ローカル画像をこれらのエンドポイントに送信する場合は、先に File Upload を作成し、返された URL を渡してください。

10 MB を超えるファイルは、先に POST /api/v1/files で File Upload を作成し、返された URL を渡してください。multipart または URL ソースの File Upload は最大 50 MB のファイルを受け付けます。File Upload の URL も 1 時間後に期限切れになるため、その時間を過ぎてから開始する Task では新しい File Upload を作成してください。

SHELL 
# For this model, non-PNG/JPEG input may return 409 depending on the selected service.
# If rejected, convert WebP/BMP/TIFF/GIF to PNG/JPEG or select a compatible service.
# Actual MIME determines support, even for a .png URL. Rejection happens before task creation or charging.
# This is not a format limit for every service. Existing Task queries remain available.
curl -X POST "https://runapi.ai/api/v1/seedream/decompose_layers" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"seedream-5-pro-layer-decomposition","image_url":"https://cdn.runapi.ai/public/samples/image.png"}'

タスクの重複作成を防ぐ

タスク作成エンドポイントは、最大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、エンドポイント固有の結果フィールド、およびその Task の float USD 金額である usage.cost が含まれます。必要な結果を保存し、ポーリングを停止します。すべてのメディアエンドポイントが同じフィールドを返すと仮定せず、正確な結果の形式についてはエンドポイントの API リファレンスを参照してください。

作成、processing、および failed の Task envelope は usage を含めません。

メディアに基づく最終精算が必要なタスクは、最終的な請求額が記録されるまで processing のままです。完了コールバックは精算後にのみ送信され、 その usage.cost は以降のタスク照会で返される値と一致します。 会計に必要な情報が不足している場合、ゼロとして報告されることはありません。 情報の照合が完了するまで、タスクは processing のままです。 請求額がゼロであると確認された場合は、usage.cost: 0 が返されます。

失敗の処理

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 つのライフサイクルイベントに対応します。completed コールバックは completed ポーリングレスポンスと usage.cost を共有し、作成、processing、failed コールバックは usage を含めません。ターミナルコールバックにはターミナルポーリングレスポンスと同じ結果フィールドが含まれます。一部のエンドポイントは processing コールバックも送信します。成功した HTTP レスポンスを迅速に返し、配信が遅延したりコールバックハンドラーが利用できない場合の調整のためにポーリングも利用可能な状態に維持してください。

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

Vidu Q4 ビデオを生成する

POST /api/v1/vidu/image_to_video は model: "vidu-q4-image-to-video" および first_frame_image_url と一緒に使用します。 POST /api/v1/vidu/reference_to_video を model: "vidu-q4-reference-to-video"、空白でない prompt、および 1 ～ 15 の順序で使用します reference_image_urls。作成時に GET を使用して各タスクを取得します /:id が続くパス。完了したタスクには、videos 配列が含まれます。 結果の URL。完成のために callback_url を指定することもできます 通知。

両方のエンドポイントは 3 ～ 16 の整数 duration_seconds を受け入れます (デフォルト) 5、および 540p、720p、1080p、2k、または 4k の output_resolution、 デフォルトは720p。 audio は JSON ブール値で、デフォルトは true です。明示的な false は、生成されたオーディオを無効にします。プロンプトは最大 20,000 件を受け入れます 文字。画像からビデオへのプロンプトはオプションであり、最初のフレーム アスペクト比を決定します。ビデオへの参照は aspect_ratio を受け入れます 16:9、9:16、1:1、4:3、または 3:4、デフォルトの 16:9、および最大 3 reference_audio_urls。

パブリック HTTP(S) メディア URL を使用します。画像は JPG/JPEG、PNG、または WEBP である必要があります。 最初のフレームの画像は 50 MB 以下である必要があります。各参考音声 ファイルは MP3 で、長さは 3 ～ 12 秒、サイズは 50 MB 以下である必要があります。 RunAPI フィールドタイプ、URL スキーム、および参照カウントをチェックします。世代 プロバイダーはリモート メディアの形式、サイズ、音声の長さをチェックします 非同期的に。無効なメディアにより、タスクが失敗する可能性があります。 通常の故障と返金の流れ。

画像から動画の料金. 参照画像から動画の料金.