Как устроен PopNow API
Что можно создавать через API, пять понятий, на которых держится вся документация, и в каком порядке читать.
PopNow API позволяет вашим программам использовать те же модели изображений, видео и аудио, что и на popnow.ai. Те же модели, те же цены, те же кредиты — только вызываются из кода, а не кликами в браузере.
Что можно создавать
| Результат | Примеры |
|---|---|
| Изображения | Изображение по тексту, правка по одному или нескольким референсам, апскейл, удаление фона, разделение на слои |
| Видео | Видео по тексту, видео из изображения, видео по первому и последнему кадру, видео по референсу, продление и монтаж клипов, синхронизация губ, говорящие аватары |
| Аудио | Музыка, звуковые эффекты, озвучка текста, звук для готового видео, расшифровка речи |
Полный список с ID и ценой каждой модели — на странице Модели. API охватывает только генерацию изображений, видео и аудио; чат- и текстовых моделей в нём нет.
Пять понятий, которые встречаются везде
ID модели
У всего, что можно вызвать, есть ID вида <maker>/<model>/<task>, например alibaba/wan-3.0/image-to-video или google/nano-banana-2.1/edit. Он указывается в поле model каждого запроса. Редактирование изображений всегда заканчивается на /edit. У инструментов самого PopNow, например удаления фона, производитель — popnow.
Задача
Генерация занимает от нескольких секунд до нескольких минут, поэтому каждый запрос создаёт задачу. taskId приходит сразу, а результат вы забираете, когда он готов. Задача проходит путь queued → running → одно конечное состояние: succeeded, failed или expired. Подробнее: Задачи.
Кредиты
API расходует те же кредиты, что и сайт. По базовой ставке 1 кредит = 0,01 $. Когда задача принята, резервируется максимальная цена, которой она может достичь; по завершении вы платите фактическую сумму (не больше резерва), остаток возвращается. Упавшая задача ничего не стоит. Подробнее: Кредиты и оплата.
Ключ идемпотентности
По таймауту сети нельзя понять, получил ли сервер ваш запрос. Отправляйте заголовок Idempotency-Key с каждой создаваемой задачей — тогда повтор с тем же ключом вернёт исходную задачу, а не создаст и не оплатит вторую. Подробнее: Идемпотентность.
Вебхук
Вместо того чтобы снова и снова опрашивать задачу, передайте ей callBackUrl. Когда задача завершится, PopNow отправит полный результат на этот URL с подписью, по которой видно, что он от нас. Подробнее: Вебхуки.
Как выглядит запрос
POST https://api.popnow.ai/api/v1/jobs/createTask
Authorization: Bearer sk-popnow-...
Idempotency-Key: 7d0c9a52-...
{ "model": "alibaba/wan-3.0/image-to-video",
"input": { "image_url": "https://…/photo.jpg", "prompt": "The waves roll in slowly" },
"callBackUrl": "https://your-app.example.com/hooks/popnow" }Все ответы используют одну обёртку { "code", "msg", "data", "request_id" }, где code: 200 означает успех.
В каком порядке читать
- Быстрый старт — первый результат за пять минут.
- Аутентификация — как хранить ключ и ограничить его права.
- Модели — выбрать модель и разобраться в её параметрах.
- Задачи и Вебхуки — полный жизненный цикл.
- Медиа — как отправить свои изображения, видео и аудио.
- Ошибки и Лимиты запросов — перед запуском в продакшен.
Хотите попробовать модель, прежде чем писать код? У каждой модели на её API-странице на popnow.ai есть Playground: он работает от вашего аккаунта и не требует ключа.