VelsVisual: как установить и пользоваться

VelsVisual — консольная утилита, которая через один API генерирует картинки, видео, музыку и озвучку: Seedance, Veo, Kling, Nano Banana, Suno, ElevenLabs и десятки других моделей вызываются одной и той же командой. Работает поверх kie.ai, написана на Node.js без единой внешней зависимости, лицензия MIT. Ниже — установка, первая генерация и разбор того, что обычно ломается.

Что это такое

Обычно каждая модель — это свой сайт, свой личный кабинет и своя форма загрузки. VelsVisual убирает этот зоопарк: вы работаете в терминале, а платформа kie.ai выступает единой точкой доступа к моделям и единым кошельком. Одна команда run — и неважно, картинка это, ролик или озвучка.

Вторая идея важнее первой: каталог моделей не зашит в программу. Список моделей и описание их полей утилита каждый раз берёт из живой документации kie.ai. Поэтому модель, вышедшая вчера, вызывается уже сегодня — обновлять для этого ничего не нужно.

Схема моделей живёт отдельно от программы — поэтому новые модели работают без обновления

Что понадобится

1. Node.js версии 18 или новее

   Проверить: node -v. Если Node не установлен — берите LTS-сборку с nodejs.org, на Mac удобнее через Homebrew: brew install node.

2. Аккаунт на kie.ai и ключ API

   Ключ выдаётся в личном кабинете на странице kie.ai/api-key. Это единственный секрет, который понадобится.

3. Кредиты на балансе

   Генерации оплачиваются кредитами платформы. Порядок цен: черновой ролик на 5 секунд — единицы центов, качественное видео со звуком — доллар и выше. Текущий баланс всегда под рукой: velsvisual credits.

Установка

Всё делается одной командой — она скачает утилиту и сразу запустит мастер настройки.

# установка и настройка за один заход
npx -y velsvisual setup

Мастер пройдёт три шага: возьмёт ключ (из переменной окружения или спросит вручную), проверит его запросом баланса и сохранит в ~/.velsvisual/config.json с правами 600; предложит поставить скилл visual для агента; покажет пример первой генерации.

Если утилита нужна постоянно, поставьте её глобально — тогда команда будет называться просто velsvisual:

npm i -g velsvisual          # обычная установка из npm
velsvisual --version          # проверка: velsvisual 0.2.1

Первая генерация

Команда одна и та же для всех типов контента: run, название модели, промпт. Флаг --wait заставляет дождаться результата, --download — сразу положить файлы в указанную папку.

# картинка
velsvisual run google/nano-banana 
  --prompt "рыжий кот в скафандре, кинематографично" 
  --wait --download ./out

# видео из своей картинки — локальный файл загрузится автоматически
velsvisual run veo3_fast --prompt "кот машет лапой" --image ./cat.png 
  --set aspect_ratio=16:9 --wait --timeout 900 --download ./out

# озвучка
velsvisual run elevenlabs/text-to-speech-turbo-2-5 
  --prompt "Привет! Это тестовая озвучка." --wait --download ./out

Как выбрать модель

Моделей на платформе несколько сотен, и половина названий ничего не говорит. Есть три команды, которые закрывают выбор.

Подсказать лучшее — recommend показывает свежие версии популярных семейств с ценами и пометкой, за что вы платите:

$ velsvisual recommend video
Рекомендуемые модели (video) — последняя версия каждого популярного семейства:
1. bytedance/seedance-2-5  [баланс цена/качество]
   ~17–114 кредитов per second (~$0.085–$0.57)
2. veo3  [максимальное качество]
   ~5–380 кредитов per video (~$0.025–$1.85)
3. kling-3.0/video  [бюджетно, для объёма]
   ~14–67 кредитов per second (~$0.070–$0.34)

Найти конкретное — models ищет по названию и категории, понимает синонимы (edit, image-to-image и remix — одно и то же):

velsvisual models --category video --search seedance
velsvisual pricing --search veo3        # цены в кредитах и долларах

Понять, что модель принимает — schema печатает список полей с типами, допустимыми значениями и значениями по умолчанию. Это же знание утилита использует сама: перед запуском она читает схему и проверяет обязательные поля до обращения к сети, а поля с умолчаниями подставляет за вас.

velsvisual schema bytedance/seedance-2-mini

Долгие задачи

Видео генерируется минутами, и держать терминал открытым не всегда удобно. Без --wait команда сразу печатает идентификатор задачи, а дальше вы возвращаетесь к ней когда угодно.

taskId печатается сразу, а забрать результат можно позже — но в пределах суток

velsvisual run bytedance/seedance-2-mini --prompt "..."   # печатает taskId
velsvisual status <taskId>                                # где сейчас задача
velsvisual wait <taskId>                                  # дождаться и вывести ссылки
velsvisual download <URL> -o video.mp4

Команды

Полезные флаги run: --set поле=значение — задать любое поле модели, --json-input — передать сразу объект JSON, --dry-run — показать готовый запрос и ничего не отправлять, --timeout и --interval — параметры ожидания. Общий флаг --json переводит вывод в машинный формат, если вы обвязываете утилиту своим скриптом.

Скилл для агента

В комплекте идёт скилл visual — инструкция, по которой Claude сам вызывает эту утилиту: подбирает модель, читает её схему, ставит задачу и скачивает результат. Ставится мастером или отдельной командой:

npx -y skills add nick-vels/VelsVisual   # поставить скилл
npx -y skills update visual              # обновить его

Каталог моделей в скилл намеренно не зашит: агент каждый раз запрашивает живой список. Если вы работаете со скиллами в настольном приложении Claude, а не в терминале, — на сайте есть отдельная инструкция по установке скиллов.

Как не сжечь кредиты

Генераций на один ролик уходит полтора-два десятка, и черновики съедают баланс быстрее финалов. Что помогает:

• Черновики в низком разрешении. Ставьте --set resolution=480p, пока сцена не утверждена: разница в цене с 1080p кратная.
• Апскейл вместо перегенерации. Отобранный дубль поднимается отдельной моделью (topaz/video-upscale) и стоит заметно дешевле, чем повторная генерация в высоком разрешении.
• Сверяйтесь с ценой заранее — velsvisual pricing --search модель. Цены у соседних моделей одного семейства отличаются в разы.
• Проверяйте запрос всухую. --dry-run печатает итоговый JSON и не тратит ничего — удобно, когда сомневаетесь в написании полей.

Если что-то пошло не так

velsvisual run topaz/video-upscale --json-input '{"upscale_factor":"4"}' 
  --image ./clip.mp4 --wait --download ./out

Обновление и ключ

npm i -g velsvisual@latest     # обновить утилиту
npx -y skills update visual    # обновить скилл агента

Каталог моделей и схемы обновлять не нужно: они живые. Ключ лежит в ~/.velsvisual/config.json с правами 600 — файл читается только вашим пользователем. В репозитории проекта ему делать нечего: если храните команды в скриптах, передавайте ключ переменной окружения KIE_API_KEY.

Исходники, лицензия и багтрекер — на GitHub, пакет — в npm. Автор — Nick Vels, лицензия MIT.