AI 生成ファイルを保存する：PiAPI の出力 URL から永続ストレージへ
生成完了で結果は得られますが、プロバイダーの URL は永久のメディアライブラリではありません。後から開く、編集する、ダウンロードする必要があれば、自社で管理するストレージへコピーし、生成とは別に状態を追跡します。
1. 使用したモデルの出力を読む
保存したタスク ID を取得し、data.status が completed であることを確認してからファイルを抽出します。data.output の形はモデルとタスクの種類で異なります。対応する取得例を参照し、すべての応答に共通のトップレベル URL があると仮定しないでください。
例えば Kling の文書の応答には、動画リソースを持つ works 配列があります。他のモデルは別のフィールドを使います。タスク ID、モデル、タスク種別、完了時刻、選んだリソースの番号をジョブと共に保存し、再試行で同じ結果を復元できるようにします。
2. 速やかにコピーし、サービスごとの保存期限を確認する
PiAPI の出力保存文書では、サービスと保存先によって異なる保持ルールが説明されています。短い期間を定める項目も、プロバイダーの CDN 方針に従う項目もあり、旧サービスも含まれます。一つの期限を現行の全モデルに適用したり、未記載の期限を無制限と解釈したりしないでください。
完了後にWebhook またはポーリングでバックグラウンドコピーを開始します。コールバックへの応答前にジョブを永続化します。下図はアプリの状態遷移例です。これらの保存状態はアプリ側のもので、PiAPI タスク API の状態ではありません。
generation completed → copy queued → downloading → verified → saved
↘ copy failed → retry copy3. 保存済みにする前に実データを検証する
結果 URL の取得先へ PiAPI API キーを転送しないでください。接続先を制限し、リダイレクトを検証してサイズと時間に上限を設定します。HTTP 状態、実際のバイト数、期待するメディア種別、基本的な読み取り可能性を確認します。200 を返す HTML エラーページは、保存できた動画ではありません。
一時オブジェクトに書き込み、チェックサムを計算し、検証成功後に最終オブジェクトを公開します。タスク ID とリソース番号に基づく固定キーを使います。オブジェクトキー、バイト数、チェックサム、保存時刻を記録し、自社のアクセス方針に沿う管理下の URL を提供します。
4. 保存と生成の再試行を分ける
コピー失敗時も生成は完了のままにし、元データが利用できる間にコピーだけを再試行します。永続的な一意レコードで重複イベントによる二重登録を防ぎます。URL が読めなくなったらタスクを再取得して現在の出力を確認しますが、期限切れファイルの復旧は保証されません。公開前に重複イベント、途中で切れた取得、利用不能な URL を試してください。
参考：出力保存、Kling のタスク取得、Webhook。これはアプリの保存設計であり、PiAPI によるアーカイブ保持の約束ではありません。
