API — генерация видео

Доступ

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

MCP для AI-агентов

Подключите AI-агента по MCP: он сам соберёт слайды, запустит рендер и получит видео. Тот же контракт слайдов, что и у REST API, но асинхронная выдача опросом. Документация MCP →

Аутентификация

1. Откройте Профиль → Интеграции.
2. Добавьте домен, с которого будете слать запросы (например example.com), и скопируйте токен — он показывается один раз.
3. Передавайте токен в заголовке.

Authorization: Bearer <токен>

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

Лимиты

10 запросов в минуту на пользователя, общий для всех его интеграций. При превышении — 429.

Создание видео — 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; каждое поле слайда опционально (наследует дефолт).
• slide_background_image — опционально; ссылка из POST /api/images, делает слайд фото-слайдом.
• slide_audio — опционально; ссылка из POST /api/audio, своя озвучка слайда вместо TTS.
• callback_url — опционально; хост должен совпадать с доменом ключа.
• project_id — опционально; пусто → новый проект, указан → пересборка существующего (чужой → 404).

Ответ 202 Accepted:

{ "id": 42 }

Рендер асинхронный — опрашивайте статус или дождитесь колбэка.

Загрузка картинки — POST /api/images

Локальный файл отправляется как multipart/form-data в поле image; возвращается непрозрачная ссылка:

curl -X POST https://ваш-домен/api/images \
  -H "Authorization: Bearer <токен>" \
  -H "Accept: application/json" \
  -F "image=@photo.png"

→ 201 { "reference": "..." }

Ссылку передайте в slides[].slide_background_image при вызове POST /api/videos. Форматы: jpeg, png, gif, webp; до 10 МБ. Ограничение: 60 запросов в минуту.

Загрузка озвучки — POST /api/audio

Локальный аудиофайл отправляется как multipart/form-data в поле audio вместе с согласием consent; возвращается непрозрачная ссылка и длительность записи:

curl -X POST https://ваш-домен/api/audio \
  -H "Authorization: Bearer <токен>" \
  -H "Accept: application/json" \
  -F "audio=@recording.mp3" \
  -F "consent=1"

→ 201 { "reference": "...", "duration_seconds": 12.34 }

Ссылку передайте в slides[].slide_audio при вызове POST /api/videos. На слайде озвучка заменяет TTS и удлиняет слайд под запись. Форматы: MP3, M4A, AAC, OGG, WEBM, WAV — определяются по содержимому; до 5 минут и 20 МБ. consent обязателен. duration_seconds возвращается сервером и не принимается на вход. Ограничение: 10 запросов в минуту, не более 2 одновременных обработок; при превышении — 429 с code: rate_limited и retry_after.

Статус рендера — GET /api/videos/{id}

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

status: pending → processing → completed | failed.

Колбэк

По завершении (успех или ошибка) сервер отправляет POST на callback_url:

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

При ошибке: status: "failed", video_url: null, error — сообщение. Один вызов, без ретраев; при недоставке опрашивайте GET /api/videos/{id}.

Ошибки

• 401 — отсутствует или неверный токен.
• 404 — видео/проект не найден (или project_id чужого пользователя).
• 422 — невалидная спецификация: { "message": "Ошибка валидации.", "errors": { "slides": ["..."] } }. Для озвучки — code: validation_failed с сообщением в audio или code: consent_required.
• 429 — превышен лимит запросов; для одновременной нормализации озвучки — code: rate_limited и retry_after в секундах.

Примеры (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 <токен>"