Задачи

Каждая генерация — это задача. Вы создаёте её одним вызовом, дальше она выполняется сама, а результат вы забираете, когда он готов: запросом, ожиданием в первом же вызове или через вебхук.

Создание задачи

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, и вы продолжаете опрос или ждёте вебхук.

Подходит для изображений и коротких аудио; видео почти всегда идёт дольше 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-ключ при скачивании.

Сначала вебхуки, опрос — про запас

Опрос работает, но вебхук дешевле для обеих сторон: вы узнаёте о результате сразу и не тратите запросы в промежутке. Надёжная интеграция использует и то и другое: вебхуки в обычном режиме и время от времени проход по 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. Удалить можно только завершённую задачу, повторный вызов безопасен.

Что дальше

• Вебхуки — получать результаты без опроса.
• Медиа — загрузить свои референсные файлы.
• Ошибки — все коды и стоит ли повторять.