動画タスクの流れ

PopGo の動画生成は非同期タスクです。送信後にタスク ID を保存し、状態をポーリングして、完了後に結果を取得します。

エンドポイントとフィールド

POST https://api.popgo.site/v1/videos
GET  https://api.popgo.site/v1/videos/{task_id}
GET  https://api.popgo.site/v1/videos/{task_id}/content
Authorization: Bearer YOUR_API_KEY

フィールド	説明
model, prompt	必須の公開モデル ID とシーン・動作の指示
duration / seconds	選択したモデルで許可された値
resolution、aspect_ratio	モデルで許可された解像度と比率
参照フィールド	モデルページに記載された画像、動画、音声の入力

curl -X POST https://api.popgo.site/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"YOUR_MODEL","prompt":"A bamboo forest in morning mist, slow camera movement","seconds":5,"resolution":"480p","aspect_ratio":"16:9"}'

ポーリングと進捗

状態は通常 queued、in_progress、completed、failed です。progress が返る場合だけパーセントを表示し、無い場合は処理中と表示します。完了後は結果 URL または /content を使います。400 はモデル、型、時間、解像度、比率、参照数を確認します。料金はポーリング回数ではなくモデル設定に従います。

照会、タイムアウト、再試行

作成は一度だけ行いid、モデル、時間、解像度、モードを保存。タイムアウトが受付後に起きることもあるため既存タスクを先に確認します。同じidの照会・ダウンロード再試行は別動画を作りません。

通常3–5秒、C10–15秒、Kling約10秒で最低15分待機。429/502/503や一時的ネットワーク障害はRetry-Afterと上限付きバックオフを使います。400は入力修正、401/403は認証・権限修正。クライアント期限では待機超過と表示しIDを保持、サービス失敗と断定しません。

progressは0から100へ直接変わるか欠落する場合があります。model、usage、解像度、実時間、fpsも省略され得ます。送信値と実ファイルを確認し、usageなしを無料と解釈しません。queued/in_progressは失敗ではありません。

URLは期限切れや認証があり得るためPopGo /contentを優先。completed後は内容取得を限定再試行し再作成しません。大ファイルには十分な時間を取り、JSONエラーではなく動画か確認。外部ホストへAPI Keyを送りません。

診断の五段階

段階	証明できること	証明できないこと
画面検証	モード・数・取得元のローカル受付	未送信はサービス拒否ではない
PopGo解析・機能検証	400/500が作成前かどうか	ログなしだけで提供側故障とは言えない
送信ペイロード	画像・動画・音声の欄とrole	欄が正しくても取得成功は保証しない
受付・照会	ID、状態、失敗段階	200やIDは参照使用・無料の証拠ではない
最終媒体	フレーム・被写体・動作・音への効果	URLだけでは品質の証拠にならない

モデル、時刻、仮ID、モード、素材数・取得元、短いエラーを記録。Key、Cookie、署名URL、私物素材は含めません。容量と審査を分け、失敗も請求を確認。新しい費用を発生させる前に原因を修正します。