Skip to content
Back to search

velsvisual

SkillWorks with Claude CodeGitHub

CLI для Claude Code для генерации фото, видео и аудио через KIE. Один инструмент поверх всех API платформы: Seedance, GPT Image, Wan, ElevenLabs и десятки других моделей.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nick-vels--velsvisual/badge.svg)](/listings/nick-vels--velsvisual)

HTML

<a href="/listings/nick-vels--velsvisual"><img src="/api/listings/nick-vels--velsvisual/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npx -y velsvisual setup

`npx` скачает CLI и сразу запустит мастер настройки (см. ниже). Для постоянной установки: `npm i -g velsvisual`. Альтернативы — прямо из GitHub (`npm i -g github:nick-vels/VelsVisual`) или из локальных исходников (`npm install -g .` в корне репозитория). Если пакет уже установлен — мастер доступен как `velsvisual setup` (alias: `init`).

Мастер проведёт по шагам:

1. **API-ключ** — предложит взять `KIE_API_KEY` из окружения или ввести вручную (ключ выдаётся на https://kie.ai/api-key), проверит его запросом баланса и сохранит в `~/.velsvisual/config.json` (chmod 600). 2. **Скилл для агента** — установит скилл `visual` командой `npx -y skills add nick-vels/VelsVisual` или скопирует его из пакета локально (`velsvisual setup --local`). Другой источник — флаг `velsvisual setup --repo владелец/репозиторий`. 3. Покажет сводку и пример первой генерации.

Неинтерактивный режим: `velsvisual setup --yes` (берёт ключ из env). Без мастера: `export KIE_API_KEY=ваш_ключ` или `velsvisual config --set-key ваш_ключ`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 185 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ```
  2. __ _______ _ ____ __ _____ ____ _ _ _ _
  3. \ \ / / ____| | / ___| \ \ / /_ _/ ___|| | | | / \ | |
  4. \ \ / /| _| | | \___ \ \ \ / / | |\___ \| | | |/ _ \ | |
  5. \ V / | |___| |___ ___) | \ V / | | ___) | |_| / ___ \| |___
  6. \_/ |_____|_____|____/ \_/ |___|____/ \___/_/ \_\_____|
  7. ```
  8. # VelsVisual
  9. [![npm](https://img.shields.io/npm/v/velsvisual.svg)](https://www.npmjs.com/package/velsvisual)
  10. [![CI](https://github.com/nick-vels/VelsVisual/actions/workflows/ci.yml/badge.svg)](https://github.com/nick-vels/VelsVisual/actions/workflows/ci.yml)
  11. [![node](https://img.shields.io/node/v/velsvisual.svg)](https://nodejs.org)
  12. [![license](https://img.shields.io/npm/l/velsvisual.svg)](LICENSE)
  13. CLI на Node.js для генерации **фото, видео и аудио** через [KIE API](https://kie.ai) (docs.kie.ai).
  14. Один инструмент поверх всех API платформы: универсальный Market API (jobs), Seedance,
  15. GPT Image, Wan, Suno, ElevenLabs и десятки других моделей.
  16. **Ноль runtime-зависимостей** — только Node.js >= 18.
  17. ## Установка и онбординг — одной командой
  18. ```bash
  19. npx -y velsvisual setup
  20. ```
  21. `npx` скачает CLI и сразу запустит мастер настройки (см. ниже). Для постоянной
  22. установки: `npm i -g velsvisual`. Альтернативы — прямо из GitHub
  23. (`npm i -g github:nick-vels/VelsVisual`) или из локальных исходников
  24. (`npm install -g .` в корне репозитория). Если пакет уже установлен — мастер
  25. доступен как `velsvisual setup` (alias: `init`).
  26. Мастер проведёт по шагам:
  27. 1. **API-ключ** — предложит взять `KIE_API_KEY` из окружения или ввести вручную
  28. (ключ выдаётся на https://kie.ai/api-key), проверит его запросом баланса
  29. и сохранит в `~/.velsvisual/config.json` (chmod 600).
  30. 2. **Скилл для агента** — установит скилл `visual` командой
  31. `npx -y skills add nick-vels/VelsVisual` или скопирует его из пакета
  32. локально (`velsvisual setup --local`). Другой источник — флаг
  33. `velsvisual setup --repo владелец/репозиторий`.
  34. 3. Покажет сводку и пример первой генерации.
  35. Неинтерактивный режим: `velsvisual setup --yes` (берёт ключ из env).
  36. Без мастера: `export KIE_API_KEY=ваш_ключ` или `velsvisual config --set-key ваш_ключ`.
  37. ## Обновление
  38. ```bash
  39. npm i -g velsvisual@latest # обновить CLI (если установлен глобально)
  40. npx -y skills update visual # обновить скилл агента (alias: upgrade)
  41. velsvisual --version # проверить версию
  42. ```
  43. - Через `npx -y velsvisual ...` версия всегда свежая — обновлять нечего.
  44. - Из GitHub (свежий main до публикации релиза): `npm i -g github:nick-vels/VelsVisual`.
  45. - Из локальных исходников: `git pull && npm install -g .` в корне репозитория.
  46. - Скилл можно и переустановить поверх: `npx -y skills add nick-vels/VelsVisual`.
  47. Восстановить ровно те версии, что записаны в `skills-lock.json`:
  48. `npx -y skills experimental_install`.
  49. - **Каталог моделей и схемы обновлять вручную не нужно** — они живые и не зависят
  50. от версии CLI (кэш 24ч). Принудительно: `velsvisual models --refresh`
  51. и `velsvisual run ... --refresh-schema`.
  52. ## Примеры
  53. ```bash
  54. # Картинка (text-to-image) — создать задачу, дождаться, скачать в ./out
  55. velsvisual run google/nano-banana --prompt "рыжий кот в скафандре, кинематографично" \
  56. --wait --download ./out
  57. # Видео из картинки: локальный файл будет сначала загружен через upload API
  58. velsvisual run veo3_fast --prompt "кот машет лапой" --image ./cat.png \
  59. --set aspect_ratio=16:9 --wait --timeout 900 --download ./out
  60. # Музыка (Suno, custom mode)
  61. velsvisual run suno --prompt "песня про осенний город" \
  62. --set customMode=true --set style="indie rock, female vocal" --set title="Осень" \
  63. --wait --download ./out
  64. # Озвучка (ElevenLabs TTS)
  65. velsvisual run elevenlabs/text-to-speech-turbo-2-5 \
  66. --prompt "Привет! Это тестовая озвучка." --wait --download ./out
  67. # Апскейл изображения
  68. velsvisual run topaz/image-upscale --image ./photo.png --wait --download ./out
  69. ```
  70. Без `--wait` команда `run` сразу печатает `taskId`; дальше — асинхронный паттерн:
  71. ```bash
  72. velsvisual status <taskId> # статус (API определяется автоматически)
  73. velsvisual wait <taskId> # блокирующее ожидание, печатает resultUrls
  74. velsvisual download <URL> -o file.png
  75. ```
  76. URL результатов живут ограниченное время (~24 часа) — скачивайте сразу
  77. (`--download КАТАЛОГ` вместе с `--wait`).
  78. ## Реестр моделей обновляется сам
  79. Модели на kie.ai выходят каждую неделю, поэтому каталог не зашит в код:
  80. - `velsvisual models` — показывает **живой реестр**: CLI скачивает каталог
  81. с https://docs.kie.ai/llms.txt и market-страницы документации.
  82. - Кэш — `~/.velsvisual/models-cache.json`, авто-обновление раз в 24 часа;
  83. принудительно — `velsvisual models --refresh`.
  84. - Если сети нет: свежий кэш → старый кэш → встроенный seed-реестр.
  85. Источник (`live`/`cache`/`seed`) и дата указываются в выводе.
  86. - Метаданные seed-моделей (обязательные поля, тип API) всегда приоритетны;
  87. новые модели из каталога просто добавляются. Seed-модели, пропавшие из
  88. живого каталога, помечаются `[stale]` — они могли быть переименованы.
  89. Модели выделенных API (`suno`, `veo3*`, `flux-kontext-*`, `gpt4o-image`,
  90. `runway-gen3`) живут вне market-каталога и `[stale]` не помечаются.
  91. ## Новые модели работают без обновления CLI
  92. `run` перед запуском читает схему модели из её документации (кэш
  93. `~/.velsvisual/schema-cache.json`, TTL 24ч) и выводит из неё:
  94. - куда положить `--prompt` (`prompt`, `text`, …) и `--image`
  95. (`image_url`, `image_urls`, `input_urls`, `first_frame_url`, `image`, …);
  96. - какие поля обязательны — проверка происходит до сетевого запроса;
  97. - обязательные поля, у которых есть значение по умолчанию, подставляются сами
  98. (иначе API отвечает 422 на, казалось бы, корректный запрос).
  99. Поэтому модель, вышедшая на kie.ai вчера, вызывается обычным
  100. `velsvisual run <новая-модель> --prompt ... --image ...`. Если модели нет
  101. в кэше реестра, `run` обновит каталог сам. Флаги: `--no-schema` (не ходить
  102. за схемой), `--refresh-schema` (обновить кэш), `--dry-run` (показать итоговый
  103. запрос и ничего не отправлять).
  104. Поля модели можно посмотреть напрямую:
  105. ```bash
  106. velsvisual schema bytedance/seedance-2-mini # таблица полей, enum, дефолты
  107. velsvisual schema bytedance/seedance-2-mini --raw # плюс сырой YAML схемы
  108. ```
  109. Соответствие встроенного seed-реестра живым схемам проверяется скриптом
  110. `npm run audit:registry` (ненулевой exit code, если что-то разошлось).
  111. ## Команды
  112. | Команда | Назначение |
  113. | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
  114. | `velsvisual setup [--yes] [--local] [--repo РЕПО]` | мастер настройки (ключ + скилл агента) |
  115. | `velsvisual credits` | баланс кредитов |
  116. | `velsvisual models [--refresh] [--category image\|video\|audio] [--search ТЕКСТ]` | живой реестр моделей (`--search` с синонимами: `edit` = `image-to-image` = `remix`) |
  117. | `velsvisual recommend image\|video\|audio [--refresh]` | подбор модели: последние версии популярных семейств с ценами и тиром качества |
  118. | `velsvisual pricing [--refresh] [--category image\|video\|audio] [--search ТЕКСТ]` | цены моделей в кредитах и $ (живой прайс kie.ai, кэш 24ч) |
  119. | `velsvisual schema МОДЕЛЬ [--raw]` | поля input модели из её документации |
  120. | `velsvisual upload ФАЙЛ` | загрузка локального файла →`fileUrl` |
  121. | `velsvisual run МОДЕЛЬ [--prompt] [--image ...] [--set k=v ...] [--json-input JSON] [--dry-run] [--wait] [--timeout] [--interval] [--download КАТАЛОГ]` | создание задачи генерации |
  122. | `velsvisual status TASK_ID [--api ...]` | статус; без`--api` — автоперебор jobs → veo → suno → gpt4o → flux → runway |
  123. | `velsvisual wait TASK_ID [--timeout 600] [--interval 5] [--api ...]` | polling до success/fail |
  124. | `velsvisual download URL [-o ПУТЬ]` | скачать файл |
  125. | `velsvisual config --set-key KEY` | сохранить API-ключ |
  126. Общий флаг `--json` — машинный вывод JSON. При ошибке API — ненулевой exit code
  127. и сообщение с `code`/`msg` (401 ключ, 402 кредиты, 422 валидация, 429 rate limit,
  128. 451 входное изображение, 455 maintenance, 501 генерация не удалась).
  129. ## Скилл для агента
  130. Готовый скилл с инструкцией по работе с CLI: [`skills/visual/SKILL.md`](skills/visual/SKILL.md)
  131. (входит в пакет). Установка и обновление:
  132. ```bash
  133. velsvisual setup # мастер: ключ + скилл
  134. npx -y skills add nick-vels/VelsVisual # только скилл
  135. npx -y skills update visual # обновить установленный скилл
  136. velsvisual setup --local # скопировать скилл из пакета в ./.agents/skills
  137. ```
  138. Каталог моделей в скилл намеренно не зашит: актуальный список агент каждый раз
  139. получает из живого реестра (`velsvisual models --refresh`), а поля конкретной
  140. модели — из `velsvisual schema МОДЕЛЬ`.
  141. ## Тесты
  142. ```bash
  143. npm test # node:test, без сети
  144. npm run audit:registry # сверка seed-реестра с живыми схемами docs.kie.ai (нужна сеть)
  145. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.