Vercel AI Gateway、非同期動画生成をサポートへ

AI Gateway での動画生成が非同期処理に対応しました。

デフォルトでは、generateVideo は結果が準備されるまで AI Gateway への HTTP リクエストを保持し続けます。動画生成には数秒から数分かかるため、このリクエストがタイムアウト超過になる可能性があります。

非同期生成を利用すれば、アプリケーションは Webhook を受け取るか、完了状態をポーリングするか、あるいは生成を開始して後続のリクエストで結果を取得することが可能になります。

プロセスが継続実行できるかどうかや、Webhook の受信が可能かどうかに応じて、以下のオプションから選択してください。

既存の generateVideo コールはこれまで通り動作します。すべてのオプションで、テキストから動画へ（text-to-video）、画像から動画へ（image-to-video）、参照映像からの生成（reference-to-video）など、さまざまな入力形式に対応しています。

SDK のアップグレード

最新の AI SDK と AI Gateway プロバイダーをインストールしてください。

非同期動画生成の利用

generateVideo で Webhook を利用する

Webhook を generateVideo に渡すことで、ポーリングを行わずに完了イベントを待機できます。ジョブが完了または失敗すると、AI Gateway がイベントを送信します。SDK はそのイベントを待ち、生成された動画をフェッチして、元の generateVideo コールを解決します。

呼び出しプロセスと Webhook ハンドラーは、配信を正しい生成ジョブに紐付けるために共有トークンとストレージが必要です。このワークフローのために generateVideo が署名シークレットを公開することはありません。完全な受信パターンについては、Webhook 検証ドキュメントを参照してください。

generateVideo のポーリングと Webhook の両方のオプションは、結果として GeneratedFile オブジェクト（result.videos）を返します。SDK はプロバイダーがホストする動画をダウンロードするため、いずれのワークフローでも uint8Array、base64、mediaType を利用可能です。

generateVideo でポーリングを行う

既存の generateVideo 呼び出しにポーリングを追加するには：

AI Gateway が非同期ジョブを開始し、SDK はジョブが完了するまで一定間隔で短いステータス要求を送信します。呼び出し元のプロセスは generateVideo の解決（レスポンス取得）まで稼働し続ける必要がありますが、個別の AI Gateway へのリクエストが生成全体を保持し続けるわけではありません。

ジョブを開始して後から取得する

startVideo は、AI Gateway がジョブを受け付けた時点で即座に操作オブジェクトを返します。レンダリング完了を待たずに、この操作オブジェクトを保存しておき、同じプロセス内または別のプロセスから later に getVideoStatus を呼び出す際に渡してください。

この操作オブジェクトは JSON シリアライズ可能であるため、データベースへの保存やキュー経由での転送が可能です。本ワークフローには組み込みのタイムアウト機能がないため、ジョブの確認をどの程度継続するかはアプリケーション側で制御する必要があります。

また、startVideo に webhookUrl を指定することで、ステータス確認の代わりに完了イベントを受け取ることもできます。start のレスポンスには、Webhook の検証に使用する署名シークレットも含まれています。

generateVideo と異なり、getVideoStatus はホストされた動画をダウンロードしません。プロバイダー提供の URL またはインラインバイト列を返すだけです。ホスト URL は有効期限が切れる可能性があるため、保存が必要な動画は必ずダウンロードしてください。

非同期ジョブの監視

AI Gateway のログページでは、非同期生成が開始されると即座にその実行状況が表示されます。生成処理中は「Running（実行中）」として表示され、完了または失敗すると更新されます。

リクエストモードで「Async」を選択すると、非同期ジョブのみを表示できます。各エントリを開くと、ジョブ ID とリクエストの詳細を確認可能です。

ジョブが作成されるのは非同期ワークフローの場合のみです。通常の generateVideo 呼び出しは、動画の生成完了後に単一の完了済みリクエストとして表示されます。

サイズ制限や、再試行時のジョブ開始における整合性（idempotency）、Webhook 配信の再試行処理など、運用に関する詳細については、非同期ビデオ生成のドキュメントをご覧ください。また、すべてのビデオモデルの一覧も確認できます。