A Node.js CLI (zero dependencies, Node >= 18) calls the KIE API (kie.ai) and can generate images, video, and audio with a hundred models.
There is deliberately no model catalog in the skill — models on kie.ai come out every week, any list in a file goes stale. The source of truth is the live registry in the CLI itself. Before every generation, choose a model through it:
velsgenerate models --refresh --json # обновить реестр из docs.kie.ai (делай раз в сессию)
velsgenerate models --category image --search nano --json # поиск по id и описанию
In the output models --json each model has required (required fields),
api, docUrl (a page on docs.kie.ai with the full input schema) and markers
[stale] (old id — look for a fresh equivalent via --search).
Installation and onboarding — with one command
npx -y velsgenerate setup # скачает CLI и запустит мастер: API-ключ (с проверкой баланса) + этот скилл
If the package is already installed globally — just velsgenerate setup. For a permanent
install after npx: npm i -g velsgenerate. The key can also be set manually:
export KIE_API_KEY=ваш_ключ or velsgenerate config --set-key ваш_ключ.
If there is no key — the CLI will say so with a clear error; ask the user for the key,
do not make one up. Check: velsgenerate credits.
Commands
velsgenerate setup [--yes] [--local] [--repo РЕПО] # мастер настройки (alias: init)
velsgenerate credits # баланс
velsgenerate models [--refresh] [--category image|video|audio] [--search ТЕКСТ]
velsgenerate upload ФАЙЛ # локальный файл → fileUrl
velsgenerate run МОДЕЛЬ [--prompt ТЕКСТ] [--image ФАЙЛ_ИЛИ_URL ...] \
[--set ключ=значение ...] [--json-input 'JSON'] \
[--wait] [--timeout СЕК] [--interval СЕК] [--download КАТАЛОГ]
velsgenerate status TASK_ID [--api jobs|veo|runway|gpt4o|flux|suno]
velsgenerate wait TASK_ID [--timeout 600] [--interval 5] [--api ...]
velsgenerate download URL [-o ПУТЬ]
velsgenerate config --set-key KEY
--set k=v— the value is parsed as JSON (true,5,["a"]), otherwise a string.--json-input— a raw JSON object on top of the assembled input (any fields of any model).--image— a local path (the CLI will upload it itself via the upload API) or a ready URL.- The model registry is live: cache
~/.velsgenerate/models-cache.jsonс TTL 24ч,models --refresh— force refresh. The data source is shown in the output (live/cache/seed).
Rules (mandatory)
- Model first, then run. Do not use model ids from memory or the examples
below without checking — first
velsgenerate models --search <задача> --json. The examples in this file are illustrations of syntax, not a recommendation of specific ids. - Always add
--json— the output is machine-readable:taskId,state,urls,tracks. - Download results immediately — URLs live ~24 hours. Use
--wait --download КАТАЛОГorvelsgenerate download URLimmediately after receivingurls. - Asynchronous run → wait pattern: either immediately
run --wait --timeout 600, orrun(gottaskId) →wait <taskId>. Video and music can be generated in minutes — for them set--timeout 900or more. - New/unfamiliar model: for dynamic models api
jobs,--promptworks, fill in the remaining fields via--set/--json-inputaccording to the schema fromdocUrl(outputmodels --json) or from the model page on docs.kie.ai. - Do not pass secrets and the key in command arguments (except
config --set-key). - On an API error, look at
code: 401 — key, 402 — credits ran out, 422 — invalid input (check the model documentation), 429 — rate limit (retry later), 451 — API did not download the input image (re-upload viaupload), 455 — maintenance, 501 — generation failed.
How to choose a model for the task
velsgenerate models --category image --search text-to-image --json # картинка по тексту
velsgenerate models --category image --search edit --json # редактирование картинки
velsgenerate models --category image --search upscale --json # апскейл / удаление фона
velsgenerate models --category video --search image-to-video --json # видео из картинки
velsgenerate models --category video --search text-to-video --json # видео по тексту
velsgenerate models --category audio --json # музыка, TTS, эффекты
Choose the freshest version of the family (highest number) unless the user asked for
otherwise. Stable dedicated APIs that live outside the market catalog and are always available:
suno (music), veo3 / veo3_fast / veo3_lite (video), flux-kontext-pro /
flux-kontext-max (image editing), gpt4o-image, runway-gen3.
Typical workflows (model ids are examples, check via models --search)
Text-to-image
velsgenerate run google/nano-banana \
--prompt "рыжий кот в скафандре, кинематографичный свет" \
--wait --download ./out --json
Image-to-video (local file)
# --image сам загрузит файл через upload API
velsgenerate run veo3_fast --prompt "кот машет лапой, камера статична" \
--image ./cat.png --set aspect_ratio=16:9 \
--wait --timeout 900 --download ./out --json
Explicit two-step option: velsgenerate upload ./cat.png → substitute fileUrl
в --image or --set image_url=....
Text-to-music (Suno)
# простой режим: только промпт
velsgenerate run suno --prompt "спокойный лоуфай для учёбы" \
--wait --timeout 900 --download ./out --json
# custom mode: style и title обязательны
velsgenerate run suno --prompt "куплеты на русском про осенний город" \
--set customMode=true --set style="indie rock, female vocal" --set title="Осень" \
--set model=V5 --wait --timeout 900 --download ./out --json
In the response, each track has audioUrl (download it) and streamAudioUrl.
TTS (voiceover)
velsgenerate run elevenlabs/text-to-speech-turbo-2-5 \
--prompt "Текст, который нужно озвучить." \
--set stability=0.5 --set speed=1.0 \
--wait --download ./out --json
Upscale
velsgenerate run topaz/image-upscale --image ./photo.png \
--wait --download ./out --json
Checking a stuck task
velsgenerate status <taskId> --json # API определится автоматически
velsgenerate wait <taskId> --timeout 600 --json
Model outside the registry
velsgenerate run some/future-model --api jobs --json-input '{"prompt": "..."}' --json