Как сгенерировать видео через API: инструкция

Если видео нужно выпускать пачками или по расписанию, ручной мастер не подходит. Для этого есть REST API: вы отправляете спецификацию слайдов, сервис рендерит MP4 и отдаёт ссылку. Интеграция пригодится агентствам, разработчикам и сервисам, которые делают видео для клиентов.

Кому нужен API

• Агентствам: массовая генерация роликов для клиентов.
• Разработчикам: встроить генерацию видео в свой продукт.
• Владельцам каналов: автоматизировать выпуск по расписанию.
• Сервисам: добавлять видео как функцию к готовому тексту.

API доступен на тарифах Pro и Plus. На тарифе Base ключи не выдаются.

Шаг 1. Получите токен

1. Откройте «Профиль → Интеграции».
2. Добавьте домен, с которого будут идти запросы.
3. Скопируйте токен: он показывается один раз.

Токен привязан к домену. callback_url обязан находиться на этом домене или его поддомене.

Шаг 2. Передайте токен

Токен передаётся в заголовке запроса:

Authorization: Bearer <токен>

Без токена или с неверным токеном вернётся 401.

Шаг 3. Отправьте запрос на генерацию

Эндпоинт: POST /api/videos. Тело запроса повторяет состояние мастера в JSON:

{
  "defaults": {
    "default_duration": 3,
    "default_font_size": 56
  },
  "slides": [
    { "text": "Первый слайд" },
    { "text": "Второй слайд", "slide_duration": 4, "slide_animation": "fade-in" }
  ],
  "callback_url": "https://api.example.com/hook",
  "project_id": 123
}

Поля:

• defaults: опционально, без него применяются настройки по умолчанию.
• slides: обязательно, от 1 до 100; каждое поле слайда опционально и наследует дефолт.
• callback_url: опционально; хост должен совпадать с доменом ключа.
• project_id: опционально; пусто создаёт новый проект, указан запускает пересборку существующего.

Ответ 202 Accepted:

{ "id": 42 }

Рендер асинхронный: сразу после запроса видео ещё не готово.

Шаг 4. Проверьте статус

Эндпоинт: GET /api/videos/{id}.

{
  "id": 42,
  "status": "completed",
  "video_url": "https://ваш-домен/storage/video-slides/slides_....mp4",
  "error": null
}

status проходит путь pending → processing → completed или failed.

Шаг 5. Дождитесь колбэка (опционально)

По завершении сервер отправляет POST на callback_url с тем же телом, что и статус. Один вызов, без ретраев. Если колбэк не дошёл, опрашивайте статус вручную.

Примеры curl

Выпуск нового видео:

curl -X POST https://ваш-домен/api/videos \
  -H "Authorization: Bearer <токен>" \
  -H "Content-Type: application/json" \
  -d '{"slides":[{"text":"Привет!"}]}'

Проверка статуса:

curl https://ваш-домен/api/videos/42 \
  -H "Authorization: Bearer <токен>"

Лимиты и ошибки

• 10 запросов в минуту на пользователя, общий лимит для всех его интеграций.
• 401: нет или неверный токен.
• 404: видео или проект не найден (в том числе чужой project_id).
• 422: невалидная спецификация.
• 429: превышен лимит запросов.

Полное описание в документации API.

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

На каких тарифах доступен API?

На Pro и Plus. На Base ключи не выдаются.

Как узнать, что видео готово?

По колбэку на callback_url или опросом GET /api/videos/{id} до статуса completed.

Можно ли пересобрать существующее видео?

Да. Укажите project_id в запросе, и рендер пересоберёт проект.

Сколько слайдов принимает API?

От 1 до 100 в одном запросе.

Итог

Получите токен, отправьте спецификацию на POST /api/videos, дождитесь статуса completed и заберите ссылку на MP4.

Откройте документацию API и соберите первую интеграцию.