Вебхуки: сообщим, как только видео будет готово

Генерация видео требует времени. На ролик в 5–10 секунд обычно уходит от нескольких минут до четверти часа, на 30-секундный — 20–30 минут, а в часы пик бывает очередь. Раньше статус задачи приходилось запрашивать каждые несколько секунд: писать цикл, обрабатывать тайм-ауты и помнить, какие задачи ещё не завершились, если ваш сервис перезапускался.

Теперь это не нужно. Как только задача завершается — успешно или с ошибкой, — мы сразу отправляем результат на ваш сервер.

Два способа получать результат

• Адрес аккаунта по умолчанию: в консоли откройте «Настройки → Вебхуки», укажите URL, на который будут приходить события, и отметьте нужные. После этого о каждой задаче на видео или изображение, отправленной через API, вы узнаете сразу по её завершении.
• Для отдельного запроса: добавьте callback_url при отправке задачи, и её результат придёт только на этот URL. Если вы привыкли писать callBackUrl, так тоже можно.

curl https://nezhagate.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "seedance-2.5", "prompt": "бумажный кораблик плывёт по дождливой ночной улице", "duration": 5,
       "callback_url": "https://your-app.com/webhooks/nezhagate"}'

Где это пригодится

• Видеоприложения, мини-программы и сайты: пользователь может закрыть страницу сразу после отправки. Когда видео готово, вам приходит уведомление — отправьте пользователю сообщение в приложении, SMS или письмо и добавьте ролик в его библиотеку.
• Массовая генерация изображений: отправьте разом сотни товарных фото или рекламных креативов — каждое изображение попадёт в вашу медиатеку или CDN, как только будет готово. Неудачные задачи фиксируются отдельно, так что можно поправить промпт и отправить их заново.
• Чат-боты: кто-то пишет промпт в группе Telegram, Discord, Lark или WeCom; бот сразу отвечает «Генерирую…», а когда приходит уведомление, публикует видео в группе.
• Serverless-функции: Vercel, Cloudflare Workers и облачные функции не рассчитаны на получасовые циклы опроса. Функция может завершиться сразу после отправки задачи — следующий шаг запустит уведомление.
• Уведомления о низком балансе: вы получите одно уведомление, когда баланс опустится ниже заданного вами числа кредитов. Направьте его в канал команды в Slack, Lark или DingTalk — и кто-нибудь пополнит баланс до того, как он закончится, а не после того, как ваш сервис остановится посреди ночи.

Можно ли на это положиться?

• Проверка подлинности: каждое уведомление подписано по схеме Standard Webhooks (той же, что у вебхуков OpenAI). Для большинства языков есть готовые библиотеки, и несколько строк кода подтвердят, что уведомление действительно пришло от нас.
• Автоматические повторы: если ваш сервер не ответит кодом 2xx в течение 10 секунд, мы повторим отправку через 1 минуту, 5 минут, 30 минут, 2 часа и 6 часов. При повторах ID события не меняется, поэтому дубликаты легко отсеять.
• Полные данные: уведомление содержит ровно то же, что возвращает эндпоинт задачи, включая URL видео и данные о расходе. Кредиты за неудачную задачу к этому моменту уже полностью возвращены, а в уведомлении указана причина ошибки.
• Журнал отправок: в консоли видны последние отправки с результатом каждой; записи хранятся 30 дней, и любую отправку можно повторить.

Настройка в три шага

1. Подготовьте на своём сервере URL, принимающий POST-запросы. В документации по вебхукам есть полные примеры проверки подписи на Python и Node.js.
2. В консоли откройте «Настройки → Вебхуки», укажите URL и нажмите «Отправить тестовое событие», чтобы убедиться, что оно доходит.
3. Отправляйте задачи как обычно и ждите уведомлений. Чтобы результат конкретной задачи пришёл на другой адрес, добавьте в этот запрос callback_url.