ガイド：画像を動画にする

動画は数秒ではなく数分かかるので、動画の連携は 1 回のリクエストで待つのではなく、タスクと Webhook を軸に組み立てます。このガイドでは、実際のモデル ID を使ってよくある使い方を説明します。

1 枚の画像を動かす

curl -X POST "https://api.popnow.ai/api/v1/jobs/createTask" \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "alibaba/wan-3.0/image-to-video",
    "input": {
      "image_url": "https://media.popnow.ai/movie/lighthouse.webp",
      "prompt": "Waves roll in slowly, clouds drift, the camera pushes gently toward the lighthouse",
      "resolution": "480p",
      "duration_seconds": 5
    },
    "callBackUrl": "https://your-app.example.com/hooks/popnow"
  }'

すぐに taskId 付きの 202 が返ります。数分後に Webhook が完了したタスクを届けるか、recordInfo で読めます。動画は output.assets[0] にあり、durationSeconds、width、height が付いています。

費用

ほとんどの動画モデルは出力 1 秒ごとの料金で、解像度が上がると単価も上がります。alibaba/wan-3.0/image-to-video なら 480p で 1 秒 6.75 クレジット、720p で 13.5、1080p で 27 です。つまり上のリクエストは 34 クレジット（5 × 6.75 を切り上げ）を確保し、成功すれば同額がかかります。

• プロンプトを詰める間は最低解像度・短い尺で回し、最終版で上げましょう。
• ユーザーに価格を見せる前に、jobs/quote で正確な金額を確認してください。
• 失敗・期限切れの動画は無料です。

最初と最後のフレームを決める

多くの画像→動画モデルは last_image_url も受け付けます。クリップは image_url から始まり、last_image_url でぴったり終わります。変身の演出や、両方に同じ画像を使ったなめらかなループに向いています。

参照動画：キャラクターや商品を一貫させる

reference-to-video モデルは、指定した最初のフレームを動かすのではなく、1 枚以上の参照画像（モデルによっては参照動画や音声も）をもとに新しい場面を作ります。

{
  "model": "minimax/h3/reference-to-video",
  "input": {
    "prompt": "The same lighthouse at night, its beam sweeping over a calm sea while the camera circles slowly",
    "reference_image_urls": ["https://media.popnow.ai/movie/lighthouse.webp"],
    "duration_seconds": 6
  }
}

参照素材をプロンプトの中でどう呼ぶかはモデルごとに違います。リファレンスページのフィールドの説明を確認してください。

クリップを長くする

video-extend モデルは、既存のクリップの最後のフレームから続きを作ります。クリップを video_url に入れ、次に起きることを書きます。

{
  "model": "minimax/h3/video-extend",
  "input": {
    "video_url": "https://media.popnow.ai/showcase/moon-picnic-loop.mp4",
    "prompt": "The camera keeps drifting right as the picnic blanket ripples in the breeze"
  }
}

クリップをつなげる延長モデルは 2 つのアセットを返します。まずつなげた全体（role: "video"）、次に新しい部分だけ（role: "segment"）です。

音

generate_audio を持つモデルはクリップにサウンドを付けます。オフにすると安くなるモデルもあります。手元の動画に音を付けたいときは popnow/foley-v1/video-to-audio を使えば、同じ動画に生成した音を付けて返します。

動画で効くプロンプト

場面だけでなく動きを書いてください。何が動くのか、どれくらいの速さか、カメラはどうするのか。「カメラがゆっくり寄り、人物が光のほうへ振り向く」ならモデルにやることがありますが、「美しい灯台」ではありません。見た目は画像がすでに伝えているので、言葉は変化に使いましょう。

本番での組み立て方

1. 元の画像をアップロードまたは保存し、popnow:// URI を控える。
2. 見積もって価格を見せ、自分のジョブ ID から作った Idempotency-Key と callBackUrl を付けて createTask を呼ぶ。
3. Webhook で署名を検証し、先に受信を返してから、動画を自分のストレージにダウンロードする。
4. 1 日 1 回 GET /api/v1/jobs で最近のタスクを一覧し、Webhook が届かなかったものを読む。

残りの項目は本番前チェックリストにあります。