visual

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

VelsVisual — 通过KIE API生成媒体内容

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

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

bash

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

基于Node.js的CLI工具（零依赖，Node版本≥18）可调用KIE API（kie.ai），支持通过数百种模型生成图像、视频与音频。

刻意不在技能中提供模型目录——kie.ai每周都会推出新模型，文件中的任何列表都会过时。权威来源是CLI中的实时注册表。每次生成前请通过CLI选择模型：

bash

velsvisual models --refresh --json       # 从docs.kie.ai更新注册表（每次会话执行一次）
velsvisual models --category image --search nano --json   # 按ID和描述搜索
velsvisual schema МОДЕЛЬ --json          # 获取该模型的真实输入字段

--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

命令前，工具会从模型文档中拉取字段schema（缓存24小时），并据此确定提示词与图片的传入位置、必填项以及带有默认值的必填项。因此，kie.ai昨日刚发布的模型无需更新CLI即可使用——无需猜测字段，也无需等待版本发布。如需关闭该功能：

--no-schema

；强制更新schema：

--refresh-schema

。

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

一键安装与配置

bash

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

bash

npx -y velsvisual setup     # 下载CLI并启动配置向导：API密钥（含余额校验）+ 本技能

若已全局安装该包，直接运行

velsvisual setup

即可。npx执行后如需永久安装：

npm i -g velsvisual

。更新方式：

npm i -g velsvisual@latest

（CLI）以及

npx -y skills update visual

（本技能）；模型目录与schema会自动更新。也可手动设置密钥：

export KIE_API_KEY=你的密钥

或

velsvisual config --set-key 你的密钥

。若没有密钥，CLI会给出清晰的错误提示；请向用户索要密钥，切勿自行编造。校验密钥：

velsvisual credits

。

Команды

命令列表

bash

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ч.

bash

velsvisual setup [--yes] [--local] [--repo 仓库地址]     # 配置向导（别名：init）
velsvisual credits                                   # 查询余额
velsvisual models [--refresh] [--category image|video|audio] [--search 文本]
velsvisual recommend image|video|audio [--refresh]   # 模型推荐：热门系列的最新版本
                                                       # 包含价格与tier（档次）
velsvisual pricing [--refresh] [--category image|video|audio] [--search 文本]  # 以KIE积分与美元计价的价格
velsvisual schema 模型ID [--raw]                     # 从模型文档中获取输入字段
velsvisual upload 文件路径                               # 本地文件 → fileUrl
velsvisual run 模型ID [--prompt 文本] [--image 文件路径或URL ...] \
    [--set 键=值 ...] [--json-input 'JSON'] [--dry-run] \
    [--wait] [--timeout 秒数] [--interval 秒数] [--download 目录]
velsvisual status 任务ID [--api jobs|veo|runway|gpt4o|flux|suno]
velsvisual wait 任务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对象，可覆盖自动生成的输入内容（支持任意模型的任意字段）。
```
--image
```
— 本地路径（CLI会自动上传）或现成的URL。
本地文件可传入任意字段：
```
--set first_frame_url=./sky.jpg
```
、
```
--set reference_image_urls='["./a.png"]'
```
——CLI会自动上传存在的路径。
```
--dry-run
```
— 显示最终输入内容但不发送请求（不消耗积分）。
缓存文件：模型注册表
```
~/.velsvisual/models-cache.json
```
，schema缓存
```
~/.velsvisual/schema-cache.json
```
，两者的TTL均为24小时。

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

规则（必须遵守）

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

先选模型，再执行生成。请勿凭记忆或下文示例使用模型ID——请先运行
```
velsvisual models --search <任务> --json
```
进行确认。本文档中的示例仅用于演示语法，并非推荐具体模型ID。
遇到陌生模型，先查schema。
```
velsvisual schema 模型ID --json
```
可提供准确的字段名、枚举值与默认值。这比触发422错误更高效。
始终添加
--json
参数——输出为机器可读格式：包含
```
taskId
```
、
```
state
```
、
```
urls
```
、
```
tracks
```
。
立即下载生成结果——URL的有效期约为24小时。请使用
```
--wait --download 目录
```
或在获取
```
urls
```
后立即执行
```
velsvisual download URL
```
。
异步模式：run → wait：要么直接执行
```
run --wait --timeout 600
```
，要么先执行
```
run
```
（获取
```
taskId
```
）再执行
```
wait <taskId>
```
。视频与音乐的生成可能需要数分钟——请设置
```
--timeout 900
```
或更长时间。
请勿用积分做测试。如需验证请求构造，请使用
```
--dry-run
```
；每次真实的
```
run
```
都会消耗积分，即使结果不符合预期。
生成前估算成本。每次真实生成（非
```
--dry-run
```
）前，请估算KIE积分（代币）与美元成本，告知用户；若超过阈值，必须请求用户确认——详见「生成前的成本估算」章节。
请勿在命令参数中传递密钥等敏感信息（
```
config --set-key
```
除外）。
API出错时请查看
```
code
```
：401——密钥问题，402——积分耗尽，422——输入无效（请与
```
velsvisual schema 模型ID
```
核对），429——请求频率超限（稍后重试），451——API未成功下载输入图片（请通过
```
upload
```
重新上传），455——维护中，500/501——生成失败（查看错误文本，调整参数通常可解决问题）。

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

生成前的成本估算（必须遵守）

Перед каждым реальным

run

(не

--dry-run

) выполни чек-лист:

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

每次真实生成（非

--dry-run

）前，请执行以下检查清单：

获取模型的KIE积分（代币）价格。首选来源：
```
velsvisual pricing --search 模型ID --json
```
——kie.ai的实时价格（缓存24小时），返回生成所需的积分与美元价格。标记
```
≈
```
/
```
approximate: true
```
表示价格是根据描述估算的，而非精确模型ID对应的价格：请告知用户这是估算值。备用来源：
```
velsvisual models --search
```
返回的
```
docUrl
```
。请考虑请求参数：价格通常取决于时长、分辨率、输出数量以及是否包含音频（同一模型可能有多个价格条目）。
转换为美元。
```
pricing
```
命令已返回
```
usd
```
字段；手动转换时，参考汇率为1积分=$0.005，但请以kie.ai/pricing页面为准，汇率可能变动。
核对余额：执行
```
velsvisual credits
```
。
生成前告知用户：模型信息、关键参数、积分与美元成本估算、当前余额以及本次消耗占余额的百分比。
若满足以下任一条件，必须请求用户确认：
- 成本估算超过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 ФАЙЛ
```
.

[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, поэтому новая модель семейства попадает в выдачу автоматически.

Если пользователь назвал задачу, но нужен ручной поиск:

bash

velsvisual models --category image --search text-to-image --json   # картинка по тексту
velsvisual models --category image --search edit --json            # редактирование картинки
velsvisual models --category image --search upscale --json         # апскейл / удаление фона
velsvisual models --category video --search image-to-video --json  # видео из картинки
velsvisual models --category video --search text-to-video --json   # видео по тексту
velsvisual models --category audio --json                          # музыка, TTS, эффекты

Выбирай самую свежую версию семейства (наибольший номер), если пользователь не просил иное. Стабильные выделенные API, которые живут вне market-каталога и есть всегда:

suno

(музыка),

veo3

veo3_fast

veo3_lite

(видео),

flux-kontext-pro

flux-kontext-max

(редактирование изображений),

gpt4o-image

runway-gen3

用户未指定模型时，请勿自行选择。执行

velsvisual recommend <类别> --json

：该命令会返回对应类别下3–4个最热门的模型系列，每个系列提供最新（顶级）版本的模型，包含积分与美元价格以及tier（

quality

——最高质量，

balanced

——平衡型，

budget

——经济型，适合批量生成）。请向用户展示这些选项及价格，并询问其更看重质量还是成本；仅在用户选择后执行生成。推荐结果不会过时：系列与版本均来自实时注册表，价格来自kie.ai的实时定价，因此新模型会自动纳入推荐列表。

若用户指定了任务，但需要手动搜索：

bash

velsvisual models --category image --search text-to-image --json   # 文本生成图片
velsvisual models --category image --search edit --json            # 图片编辑
velsvisual models --category image --search upscale --json         # 超分辨率 / 背景移除
velsvisual models --category video --search image-to-video --json  # 图片生成视频
velsvisual models --category video --search text-to-video --json   # 文本生成视频
velsvisual models --category audio --json                          # 音乐、TTS、音效

若用户未特别要求，请选择系列的最新版本（版本号最大）。稳定的独立API始终存在于市场目录之外：

suno

（音乐）、

veo3

veo3_fast

veo3_lite

（视频）、

flux-kontext-pro

flux-kontext-max

（图像编辑）、

gpt4o-image

、

runway-gen3

。

Типовые workflow (id моделей — примеры, проверяй через models --search)

典型工作流（模型ID为示例，请通过models --search确认）

Text-to-image

bash

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

bash

velsvisual run google/nano-banana \
  --prompt "穿宇航服的橘猫，电影级光影" \
  --wait --download ./out --json

Оживить готовую картинку (image-to-video)

图片动效化（image-to-video）

bash

velsvisual schema bytedance/seedance-2-mini --json   # узнать поля и дефолты
velsvisual run bytedance/seedance-2-mini \
  --prompt "облака медленно плывут, свет меняется, камера статична" \
  --image ./sky.jpg \
  --set duration=6 --set resolution=480p --set aspect_ratio=1:1 \
  --set generate_audio=false \
  --wait --timeout 900 --download ./out --json

--image

кладётся в то поле, которое реально есть у модели (

first_frame_url

image_urls

, …). Явный двухшаговый вариант:

velsvisual upload ./sky.jpg

→ подставить URL в

--set ПОЛЕ=...

bash

velsvisual schema bytedance/seedance-2-mini --json   # 获取字段与默认值
velsvisual run bytedance/seedance-2-mini \
  --prompt "云朵缓慢飘动，光影变化，镜头静止" \
  --image ./sky.jpg \
  --set duration=6 --set resolution=480p --set aspect_ratio=1:1 \
  --set generate_audio=false \
  --wait --timeout 900 --download ./out --json

--image

会自动填入模型实际存在的字段（如

first_frame_url

、

image_urls

等）。显式两步法：

velsvisual upload ./sky.jpg

→ 将URL填入

--set 字段=...

。

Text-to-music (Suno)

Text-to-music（Suno）

bash

undefined

bash

undefined

простой режим: только промпт

简易模式：仅需提示词

velsvisual run suno --prompt "спокойный лоуфай для учёбы"
--wait --timeout 900 --download ./out --json

velsvisual run suno --prompt "适合学习的舒缓lo-fi音乐"
--wait --timeout 900 --download ./out --json

custom mode: style и title обязательны

自定义模式：必须设置style与title

velsvisual run suno --prompt "куплеты на русском про осенний город"
--set customMode=true --set style="indie rock, female vocal" --set title="Осень"
--set model=V5 --wait --timeout 900 --download ./out --json


В ответе у каждого трека есть `audioUrl` (скачивать его) и `streamAudioUrl`.

velsvisual run suno --prompt "关于秋日城市的俄语歌词"
--set customMode=true --set style="indie rock, female vocal" --set title="秋日"
--set model=V5 --wait --timeout 900 --download ./out --json


返回结果中，每个音轨包含`audioUrl`（用于下载）与`streamAudioUrl`。

TTS (озвучка)

TTS（配音）

bash

velsvisual run elevenlabs/text-to-speech-turbo-2-5 \
  --prompt "Текст, который нужно озвучить." \
  --set stability=0.5 --set speed=1.0 \
  --wait --download ./out --json

Список доступных голосов — в

velsvisual schema elevenlabs/text-to-speech-turbo-2-5

(поле

voice

, enum с id голосов).

bash

velsvisual run elevenlabs/text-to-speech-turbo-2-5 \
  --prompt "需要配音的文本。" \
  --set stability=0.5 --set speed=1.0 \
  --wait --download ./out --json

可用语音列表请查看

velsvisual schema elevenlabs/text-to-speech-turbo-2-5

（

voice

字段，包含语音ID的枚举值）。

Апскейл

超分辨率

bash

velsvisual run topaz/image-upscale --image ./photo.png \
  --set upscale_factor=2 --wait --download ./out --json

bash

velsvisual run topaz/image-upscale --image ./photo.png \
  --set upscale_factor=2 --wait --download ./out --json

Проверка зависшей задачи

检查停滞任务

bash

velsvisual status <taskId> --json        # API определится автоматически
velsvisual wait <taskId> --timeout 600 --json

bash

velsvisual status <taskId> --json        # 自动识别API
velsvisual wait <taskId> --timeout 600 --json

Совсем новая модель (ещё не в каталоге)

全新模型（尚未纳入目录）

bash

velsvisual run some/future-model --api jobs --json-input '{"prompt": "..."}' --json

Если модель уже в каталоге, но появилась после последнего обновления кэша,

run

обновит реестр сам —

--api

указывать не нужно.

bash

velsvisual run some/future-model --api jobs --json-input '{"prompt": "..."}' --json

若模型已纳入目录，但在最后一次缓存更新后才发布，

run

命令会自动更新注册表——无需指定

--api

。