任务

每一次生成都是一个任务。你用一次调用创建它，它自己在后台运行；结果准备好后，你可以主动查询、在第一次请求里等它，或者通过 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：不轮询，直接接收结果。
• 素材与文件：上传你自己的参考文件。
• 错误码：每个错误码以及要不要重试。