PiratePressPiratePress

API для генерации видео: как делать ролики кодом

«API для генерации видео» — запрос разработчиков, которым ролики нужны не по одному, а потоком: контент-фермы, автопостинг, интеграция в свой продукт. У PiratePress весь конвейер бота доступен через публичный REST API. Разберём его на рабочих примерах.

Что нужно подготовить

  1. API-ключ. Получается в боте: @piratepress_bot → команда /apikey. Ключ pp_… показывается один раз — сохрани сразу.
  2. HTTP-клиент. Достаточно curl; базовый URL — https://api.piratepress.fun/public/v1.
  3. Баланс дублонов. Базовый ролик — 100 дублонов (100 ₽), точная цена возвращается в ответе при создании заказа.
  4. OpenAPI-референс под рукой: https://api.piratepress.fun/public/v1/docs.

Как генерировать видео кодом

Шаг 1. Создай заказ. Два пути. Мастер-промпт одной строкой — серверная LLM сама раскладывает его в параметры:

curl -X POST https://api.piratepress.fun/public/v1/videos:quick \
  -H "X-API-Key: pp_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"prompt": "30-секундный ролик про кота-космонавта, русская озвучка"}'

Или явные параметры через POST /videos — предсказуемая конфигурация и цена:

curl -X POST https://api.piratepress.fun/public/v1/videos \
  -H "X-API-Key: pp_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"theme": "история про кота-космонавта", "lang": "ru", "duration": "30", "caption_mode": "karaoke", "bg_ai": "illustrations"}'

Заголовок Idempotency-Key (uuid) обязателен: повтор с тем же ключом вернёт тот же заказ вместо дубля. Ответ — {id, cost, eta_seconds}.

Шаг 2. Полли статус. GET /videos/{id} возвращает PublicVideoOut: status (queued → running → done / error / refunded), cost, при done — result_url (подписанная ссылка на mp4, TTL 7 дней), result_urls для батчей и metadata — постинг-пак (title, description, hashtags). Полли не чаще раза в 20–30 секунд или подпишись на webhook.

Шаг 3. Скачай результат сразу. Ссылка живёт неделю — забирай mp4 сразу после done.

Шаг 4. Масштабируй. Пакетная генерация — поле count (1–50 роликов в заказе). Свои файлы (паки темы, фоны, треки, образец голоса) грузятся через POST /assets (multipart), возвращённый id передаётся полями *_asset_id.

Частые ошибки

Запросы без идемпотентности. Ретрай без Idempotency-Key — дубль заказа и двойное списание. Ключ должен быть уникальным на логическую операцию и сохраняться для ретраев.

Агрессивный поллинг. Десять запросов в секунду не ускорят рендер, но съедят лимиты. 20–30 секунд между опросами, для фанатиков — webhooks (video.done).

Игнорирование статуса refunded. При фейле генерации дублоны возвращаются автоматически, а заказ уходит в refunded, а не error. Учитывай оба статуса в обработчике.

Частые вопросы

Чем videos:quick отличается от POST /videos? Quick — свободный промпт с маппингом через LLM (может уехать от темы, цена известна после создания, маппер троттлится). Явные параметры — детерминизм. Для потока используй POST /videos.

Как узнать цену до заказа? Точная цена формируется из параметров и возвращается в cost при создании. База — 100 дублонов, допы (AI-фон, AI-музыка и пр.) тарифицируются по прайсу.

Есть ли лимиты? Медиатека — 20 файлов, до 20 МБ на файл, 2 ГБ суммарно. Один активный API-ключ на пользователя.

Подходит ли API для продакшена? Да: идемпотентность, webhooks, пакетные заказы и авто-возвраты при фейлах сделаны именно под программный поток.

Как обрабатывать ошибки 422? Ответ содержит человекочитаемую причину: конфликт параметров, неизвестный id ассета, превышение лимитов. Логируй тело ошибки — оно сразу говорит, что поправить в заказе.

Можно ли отменить заказ после создания? Нет: заказ сразу встаёт в очередь генерации. Поэтому идемпотентные ключи и проверка параметров до отправки — твоя основная защита от случайных списаний.

Как организовать надёжный конвейер? Классическая схема: очередь тем в твоей БД → воркер создаёт заказы с сохранёнными Idempotency-Key → поллинг или webhook → скачивание mp4 и постинг-пака → публикация. Каждый шаг идемпотентен, всё переживает рестарты.

Есть ли SDK под популярные языки? Официальный клиент — MCP-сервер на Node; для Python, Go и других хватает обычного HTTP-клиента: вся поверхность — три основных вызова плюс загрузка ассетов. Примеры есть в документации.

Как тестировать интеграцию без лишних трат? Делай заказы с минимальным набором параметров: базовый ролик стоит 100 дублонов, а при фейле генерации средства возвращаются автоматически. Отладка флоу обходится в считанные рубли.

Начни с ключа: открой @piratepress_bot, команда /apikey — и первый ролик кодом через пять минут.