動画生成APIを組み込む｜非同期ジョブ・失敗・課金・結果保存を設計する

動画生成APIは、受付と完成を分け、ジョブIDを保存して追跡します。通信が切れたときに新しい生成を送り直す前に、受け付け済みのジョブがないか確認してください。

受付、待機、完成、保存を別の状態にする

RunwayのAPI入門は、タスクの作成後に完了を待って出力を受け取る例を示しています。自分のアプリでも、送信成功だけで完成と扱わない設計にします。具体的な状態名や取得方法は対象APIの現行仕様へ合わせます。

下書き → 送信中 → 受付済み → 待機・処理中 → 生成完了 → 保存済み
                    ↓                    ↓
                 状態照会              失敗の分類

これは自分のアプリ側の状態設計例で、特定APIの応答名ではありません。ジョブID、入力条件、利用者側の依頼IDを紐づけ、再読み込み後も状態を確認できるようにします。

再試行は、生成の追加か状態照会かを分ける

受付されたか不明な場合は、APIが提供する履歴や重複防止の仕組みを確認します。重複防止の機能が未確認なら、再送しても一回分の課金になるとは想定しないでください。

利用量と、入力できる範囲を制限する

モデル、尺、解像度、回数、同時ジョブ数に上限を持たせます。利用者ごとの利用量とアプリ全体の予算を確認し、上限に達したら新しい生成の受付を止めます。Web版の契約がAPIにも使えるかは別に確認してください。

APIキーをブラウザーへ渡さず、サーバー側で保管します。入力URLやアップロードを受け付ける場合は、取得先、サイズ、種類、利用できる素材かを確認します。

保存の完了までを、受け入れ試験にする

状態照会の失敗、処理失敗、保存先の容量不足を試験用の応答で再現し、二重送信や誤った完了表示がないかを確認します。結果URLの有効期間は対象APIで調べ、必要なファイルを期限内に保存する設計にします。

実APIでの有料生成を行う前に、模擬応答で受付と照会の流れを検査できます。この記事は設計手順であり、各APIで生成を実行した検証ではありません。ローカルComfyUIの実行はComfyUI APIの使い方へ分けて確認できます。