タスク

生成はすべてタスクです。1 回の呼び出しで作成すると、あとは自動で進みます。結果ができたら、問い合わせて受け取るか、最初のリクエストで待つか、Webhook で受け取ります。

タスクを作成する

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, the camera drifts toward the lighthouse",
      "resolution": "480p",
      "duration_seconds": 5
    },
    "callBackUrl": "https://your-app.example.com/hooks/popnow"
  }'

本文

ヘッダー

レスポンス

新しいタスクは HTTP 202 で返ります。

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "job_01JH8Z4Q5W2N7R3K9M6P1C0VXD",
    "state": "queued",
    "estimatedCredits": 34,
    "estimatedCost": "0.34",
    "deadlineAt": "2026-10-16T09:40:00Z"
  },
  "request_id": "req_…"
}

202 は受け付けたという意味で、完了ではありません。estimatedCredits は残高から確保された額で、このタスクにかかりうる最大額です（estimatedCost は同じ金額の米ドル表記）。作成に失敗した場合は何も作られず、確保もされません。理由は code でわかります（エラー）。

状態

知らない状態が返ってきたら「まだ終わっていない」とみなし、確認を続けてください。

wait でポーリングを省く

createTask に ?wait=<秒>（最大 60）を付けると、タスクが終わるか時間切れになるまで接続を保ちます。

• 時間内に終了 → HTTP 200 で、recordInfo と同じ形のタスク記録が返ります。data.state を確認してください。終了が成功とは限りません。
• 終わらなかった → 通常の 202 が返るので、ポーリングを続けるか Webhook を待ちます。

画像や短い音声向けです。動画はほぼ確実に 60 秒を超えます。途中で切断してもタスクは止まらず、取り消されもしません。

タスクを読む

curl "https://api.popnow.ai/api/v1/jobs/recordInfo?taskId=job_01JH8Z4Q5W2N7R3K9M6P1C0VXD" \
  -H "Authorization: Bearer $POPNOW_API_KEY"

3 つの異なる期限

• deadlineAt：タスクが実行できる時間の上限。過ぎると expired になり、確保分が戻ります。
• output.assets[].expiresAt：その署名付きリンク 1 本の有効期限で、約 20 分です。タスクを読み直せば新しいリンクがもらえ、ファイル自体は残っています。
• retention.outputsExpireAt：保存されたファイルが削除される時刻。残したいものはそれまでにダウンロードするか、アセットライブラリに保存してください。

output の中身

ほとんどのタスクはファイルを 1 つ返します。複数返すものもあります。バリエーションを作るモデルは複数枚の画像を、動画の延長はつなげた全体（role: "video"）と新しく生成した部分（role: "segment"）を、レイヤー分解はベース画像と透明レイヤー（それぞれ layer オブジェクト付き）を返します。音声の文字起こしは output.text に入ります。

出力のリンクは持っている人なら誰でも使えるリンクです。期限内は URL を知っている人がダウンロードできます。取得するときに API キーは送らないでください。

Webhook を基本に、ポーリングは保険に

ポーリングでも動きますが、Webhook のほうが双方にとって安上がりです。結果ができた瞬間にわかり、その間にリクエストを使いません。堅実なのは両方を使う方法で、普段は Webhook、ときどき recordInfo で Webhook が届かなかったタスクを拾います。

ポーリングするなら間隔を空けてください。画像は 2〜3 秒ごと、動画は 10〜15 秒ごとにし、deadlineAt で止めます。

タスク一覧

GET /api/v1/jobs は、このキーで作ったタスクを新しい順に返します。入力と出力は含みません。

curl "https://api.popnow.ai/api/v1/jobs?state=failed&from=2026-10-01&limit=50" \
  -H "Authorization: Bearer $POPNOW_API_KEY"

絞り込み：from と to（UTC の日付、最大 92 日間。既定は直近 7 日）、state、model、limit（最大 100）。hasMore が true なら、nextCursor を cursor として同じ条件で渡します。

失敗したタスクを再試行する

POST /api/v1/jobs/retry に { "taskId": "…" } を送ると、failed または expired のタスクの元の入力を使い、現在の価格で新しいタスクを作ります。元のタスクは変更されません。元のタスクがまだ終わっていなければ 409 が返ります。成功したタスクは再試行できないので、新しく作ってください。

タスクの内容を削除する

POST /api/v1/jobs/purge に { "taskId": "…" } を送ると、タスクのファイル、結果、保存されたプロンプトを削除します。課金の記録は残ります。請求額、モデル、状態、タイムスタンプはそのままで、レスポンスの billingRetained: true がそれを示しています。削除できるのは終了したタスクだけで、繰り返し呼んでも安全です。

次のステップ

• Webhook：ポーリングせずに結果を受け取る。
• メディア：自分の参照ファイルをアップロードする。
• エラー：すべてのコードと再試行の判断。