Visual

VelsVisual — генерация медиа через KIE API

CLI на Node.js (ноль зависимостей, Node >= 18) обращается к KIE API (kie.ai) и умеет генерировать изображения, видео и аудио сотней моделей.

Каталога моделей в скилле нет нарочно — модели на kie.ai выходят каждую неделю, любой список в файле устаревает. Источник истины — живой реестр в самом CLI. Перед каждой генерацией выбирай модель через него:

velsvisual models --refresh --json       # обновить реестр из docs.kie.ai (делай раз в сессию)
velsvisual models --category image --search nano --json   # поиск по id и описанию
velsvisual schema МОДЕЛЬ --json          # реальные поля input этой модели

--search понимает синонимы задач и игнорирует дефисы/регистр: edit находит и google/nano-banana-edit, и gpt-image-2-image-to-image, и ideogram/v3-remix (вендоры называют одно и то же по-разному). То же для tts/озвучка, image-to-video/оживи, upscale/апскейл.

В выводе models --json у каждой модели есть required, api, docUrl и пометка [stale] (в живом каталоге модели больше нет — ищи свежий аналог через --search).

CLI сам знает поля новых моделей. Перед запуском run подтягивает схему модели из её документации (кэш 24ч) и по ней определяет, куда класть промпт и картинку, что обязательно и какие обязательные поля имеют значения по умолчанию. Поэтому модель, вышедшая на kie.ai вчера, работает без обновления CLI — не нужно ни угадывать поля, ни ждать релиза. Отключить: --no-schema, обновить принудительно: --refresh-schema.

Установка и онбординг — одной командой

npx -y velsvisual setup     # скачает CLI и запустит мастер: API-ключ (с проверкой баланса) + этот скилл

Если пакет уже установлен глобально — просто velsvisual setup. Для постоянной установки после npx: npm i -g velsvisual. Обновление: npm i -g velsvisual@latest (CLI) и npx -y skills update visual (этот скилл); каталог моделей и схемы обновляются сами. Ключ также можно задать вручную: export KIE_API_KEY=ваш_ключ или velsvisual config --set-key ваш_ключ. Если ключа нет — CLI скажет об этом понятной ошибкой; попроси ключ у пользователя, не выдумывай его. Проверка: velsvisual credits.

Команды

velsvisual setup [--yes] [--local] [--repo РЕПО]     # мастер настройки (alias: init)
velsvisual credits                                   # баланс
velsvisual models [--refresh] [--category image|video|audio] [--search ТЕКСТ]
velsvisual recommend image|video|audio [--refresh]   # подбор модели: последние версии
                                                       # популярных семейств с ценами и тирами
velsvisual pricing [--refresh] [--category image|video|audio] [--search ТЕКСТ]  # цены в кредитах и $
velsvisual schema МОДЕЛЬ [--raw]                     # поля input модели из её документации
velsvisual upload ФАЙЛ                               # локальный файл → fileUrl
velsvisual run МОДЕЛЬ [--prompt ТЕКСТ] [--image ФАЙЛ_ИЛИ_URL ...] \
    [--set ключ=значение ...] [--json-input 'JSON'] [--dry-run] \
    [--wait] [--timeout СЕК] [--interval СЕК] [--download КАТАЛОГ]
velsvisual status TASK_ID [--api jobs|veo|runway|gpt4o|flux|suno]
velsvisual wait TASK_ID [--timeout 600] [--interval 5] [--api ...]
velsvisual download URL [-o ПУТЬ]
velsvisual config --set-key KEY

• --set k=v — значение парсится как JSON (true, 5, ["a"]), иначе строка.
• --json-input — сырой JSON-объект поверх собранного input (любые поля любой модели).
• --image — локальный путь (CLI загрузит его сам) или готовый URL.
• Локальный файл можно передать в любое поле: --set first_frame_url=./sky.jpg, --set reference_image_urls='["./a.png"]' — существующие пути загружаются автоматически.
• --dry-run — показать итоговый input и не отправлять запрос (не тратит кредиты).
• Кэши: реестр ~/.velsvisual/models-cache.json, схемы ~/.velsvisual/schema-cache.json, оба с TTL 24ч.

Правила (обязательно)

1. Сначала модель, потом запуск. Не используй id моделей из памяти или примеров ниже без проверки — сначала velsvisual models --search <задача> --json. Примеры в этом файле — иллюстрации синтаксиса, а не рекомендация конкретных id.
2. Незнакомая модель — сначала `schema`. velsvisual schema МОДЕЛЬ --json даёт точные имена полей, enum-значения и дефолты. Это дешевле, чем ловить 422.
3. Всегда добавляй `--json` — вывод машиночитаемый: taskId, state, urls, tracks.
4. Скачивай результаты сразу — URL живут ~24 часа. Используй --wait --download КАТАЛОГ или velsvisual download URL сразу после получения urls.
5. Асинхронный паттерн run → wait: либо сразу run --wait --timeout 600, либо run (получил taskId) → wait <taskId>. Видео и музыка могут генерироваться минуты — для них ставь --timeout 900 или больше.
6. Не трать кредиты на пробы. Проверять сборку запроса — через --dry-run; каждый реальный run списывает кредиты, даже если результат не понравился.
7. Считай стоимость до запуска. Перед каждым реальным run оцени цену в кредитах (токенах) и в долларах, сообщи её пользователю и при превышении порогов обязательно спроси подтверждение — см. раздел «Оценка стоимости перед генерацией».
8. Не передавай секреты и ключ в аргументах команд (кроме config --set-key).
9. При ошибке API смотри на code: 401 — ключ, 402 — кредиты кончились, 422 — невалидный input (сверься с velsvisual schema МОДЕЛЬ), 429 — rate limit (повтори позже), 451 — API не скачал входное изображение (перезалей через upload), 455 — maintenance, 500/501 — генерация не удалась (см. текст ошибки, часто помогает смена параметров).

Оценка стоимости перед генерацией (обязательно)

Перед каждым реальным run (не --dry-run) выполни чек-лист:

1. Узнай цену модели в кредитах (токенах) KIE. Первый источник — velsvisual pricing --search МОДЕЛЬ --json: живой прайс kie.ai (кэш 24ч), отдаёт цену в кредитах и в $ за генерацию. Метка ≈ / approximate: true — цена подобрана по описанию, а не по точному id: это оценка, скажи об этом пользователю. Запасной источник — docUrl из velsvisual models --search. Учитывай параметры запроса: цена часто зависит от длительности, разрешения, количества выходов и наличия аудио (у одной модели несколько ценовых записей).
2. Пересчитай в доллары. pricing уже отдаёт usd; при ручном пересчёте ориентир — 1 кредит = $0.005, но сверяйся с kie.ai/pricing, курс может меняться.
3. Сверься с балансом: velsvisual credits.
4. До запуска сообщи пользователю: модель, ключевые параметры, оценку стоимости в кредитах и в $, текущий баланс и какой процент от него составит списание.
5. Обязательно спроси подтверждение генерации, если верно хотя бы одно:

• оценка стоимости больше $1;
• оценка больше 10% текущего баланса;
• цену модели установить не удалось. Без явного «да» запрос не отправляй. При отказе предложи более дешёвый вариант (модель -fast/-mini, меньшее разрешение/длительность).

Типичные грабли

• `[500] output audio may be related to copyright restrictions` у видеомоделей (Seedance и другие с generate_audio): модель не смогла легально сгенерировать звуковую дорожку. Перезапусти с --set generate_audio=false.
• Квадратная картинка в 16:9 — модели по умолчанию ставят aspect_ratio: 16:9 и обрежут кадр. Для анимации готового изображения задавай соотношение исходника (--set aspect_ratio=1:1) или adaptive, если модель его поддерживает.
• Поле картинки называется по-разному: image_url, image_urls, input_urls, first_frame_url, image. --image подставит правильное само; при ручном --set сверься со schema.
• Дороже ≠ лучше для черновика: сначала прогони дешёвую/быструю версию модели (-fast, -mini, 480p, короткая длительность), финальный рендер — после утверждения.
• `[451]` — API не смог скачать твой URL. Перезалей файл: velsvisual upload ФАЙЛ.

Как выбрать модель под задачу