任務

每一次生成都是一個任務。你用一次呼叫建立它，它會自己在背景執行；結果準備好後，你可以主動查詢、在第一次請求裡等待，或透過 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"

三個不同的到期時間

• deadlineAt：任務最多能執行多久。超過後任務變成 expired，保留的點數退回。
• output.assets[].expiresAt：這條簽名連結的有效期限，大約 20 分鐘。再讀一次任務就有新連結，檔案本身仍在。
• retention.outputsExpireAt：儲存的檔案何時刪除。想保留的話，在這之前下載，或存進素材庫。

output 裡有什麼

大多數任務只回傳一個檔案。有些會回傳多個：模型一次產生多張變化時會有多張圖；影片延長會先給接好的完整影片（role: "video"），再給新生成的那一段（role: "segment"）；圖層拆分會給一張底圖加上數個透明圖層（每個都有 layer 物件）。語音轉文字的結果在 output.text。

產出連結是憑連結存取的：拿到 URL 的人在過期前都能下載。下載時不要帶上你的 API 金鑰。

以 Webhook 為主，輪詢備援

輪詢可行，但 Webhook 對雙方都更省：結果一出來你就知道，中間不必浪費請求。穩健的做法是兩者並用——平常靠 Webhook，偶爾用 recordInfo 掃一遍沒收到回呼的任務。

輪詢時請放慢節奏：圖片每 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 天；預設為最近七天）、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：不輪詢，直接接收結果。
• 素材與檔案：上傳你自己的參考檔案。
• 錯誤碼：每個錯誤碼以及要不要重試。