Генерация фото, видео и аудио через VelsVisual CLI и KIE API (kie.ai). Используй, когда пользователь просит «сгенерируй картинку/изображение/фото/видео/музыку/песню/озвучку/голос/саунд-эффект», text-to-image, image-to-video, TTS или апскейл изображения.

VelsVisual — генерация медиа через KIE API CLI на Node.js (ноль зависимостей, Node = 18) обращается к KIE API (kie.ai) и умеет генерировать изображения, видео и аудио сотней моделей. Каталога моделей в скилле нет нарочно — модели на kie.ai выходят каждую неделю, любой список в файле устаревает. Источник истины — живой реестр в самом CLI. Перед каждой генерацией выбирай модель через него: 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 . Установка и онбординг — одной командой Если пакет уже установлен глобально — просто 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 . Команды 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 ФАЙЛ . Как выбрать модель под задачу Пользователь не назвал модель — не выбирай молча. Выполни velsvisual recommend <категория json : команда вернёт 3–4 самых популярных семейства категории, по каждому — последнюю (топовую) версию модели с ценой в кредитах и $ и тиром ( quality — максимальное качество, balanced — баланс, budget — дёшево, для объёмов). Покажи варианты пользователю с ценами и спроси, что важнее — качество или объём; запускай только после его выбора. Рекомендации не устаревают: семейства и версии берутся из живого реестра, цены — из живого прайса kie.ai, поэтому новая модель семейства попадает в выдачу автоматически. Если пользователь назвал задачу, но нужен ручной поиск: Выбирай самую свежую версию семейства (наибольший номер), если пользователь не просил иное. Стабильные выделенные API, которые живут вне market каталога и есть всегда: suno (музыка), veo3 / veo3 fast / veo3 lite (видео), flux kontext pro / flux kontext max (редактирование изображений), gpt4o image , runway gen3 . Типовые workflow (id моделей — примеры, проверяй через models search) Text to image Оживить готовую картинку (image to video) image кладётся в то поле, которое реально есть у модели ( first frame url , image urls , …). Явный двухшаговый вариант: velsvisual upload ./sky.jpg → подставить URL в set ПОЛЕ=... . Text to music (Suno) В ответе у каждого трека есть audioUrl (скачивать его) и streamAudioUrl . TTS (озвучка) Список доступных голосов — в velsvisual schema elevenlabs/text to speech turbo 2 5 (поле voice , enum с id голосов). Апскейл Проверка зависшей задачи Совсем новая модель (ещё не в каталоге) Если модель уже в каталоге, но появилась после последнего обновления кэша, run обновит реестр сам — api указывать не нужно.