visual

VelsVisual — media generation via the KIE API

A Node.js CLI (zero dependencies, Node >= 18) calls the KIE API (kie.ai) and can generate images, videos, 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 each generation, choose a model through it:

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

--search understands task synonyms and ignores hyphens/case: edit finds and google/nano-banana-edit, и gpt-image-2-image-to-image, и ideogram/v3-remix (vendors call the same thing differently). Same for tts/озвучка, image-to-video/оживи, upscale/апскейл.

In the output models --json each model has required, api, docUrl and a note [stale] (the model is no longer in the live catalog — look for a fresh equivalent via --search).

The CLI itself knows the fields of new models. Before launching, run pulls the model schema from its documentation (24h cache) and uses it to determine where to put the prompt and the image, what is required, and which required fields have default values. That is why a model released on kie.ai yesterday works without updating the CLI — no need to guess fields or wait for a release. To disable: --no-schema, to force an update: --refresh-schema.

Installation and onboarding — with one command

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

If the package is already installed globally — just velsvisual setup. For a permanent installation after npx: npm i -g velsvisual. Update: npm i -g velsvisual@latest (CLI) и npx -y skills update visual (this skill); the model catalog and schemas update themselves. The key can also be set manually: export KIE_API_KEY=ваш_ключ or velsvisual 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: velsvisual credits.

Commands

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 — 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) or a ready URL.
• A local file can be passed to any field: --set first_frame_url=./sky.jpg, --set reference_image_urls='["./a.png"]' — existing paths are loaded automatically.
• --dry-run — show the final input and do not send the request (does not spend credits).
• Caches: registry ~/.velsvisual/models-cache.json, schemas ~/.velsvisual/schema-cache.json, both with a 24h TTL.

Rules (mandatory)

1. Model first, then run. Do not use model ids from memory or from the examples below without checking — first velsvisual models --search <задача> --json. The examples in this file are syntax illustrations, not a recommendation of specific ids.
2. Unfamiliar model — first schema. velsvisual schema МОДЕЛЬ --json gives the exact field names, enum values, and defaults. This is cheaper than catching a 422.
3. Always add --json — the output is machine-readable: taskId, state, urls, tracks.
4. Download results immediately — URLs live ~24 hours. Use --wait --download КАТАЛОГ or velsvisual download URL immediately after receiving urls.
5. Asynchronous run → wait pattern: either immediately run --wait --timeout 600, or run (got taskId) → wait <taskId>. Video and music can take minutes to generate — for them set --timeout 900 or more.
6. Do not waste credits on trials. Check the request assembly via --dry-run; every real run spends credits, even if you did not like the result.
7. Calculate the cost before running. Before every real run estimate the price in credits (tokens) and in dollars, tell the user, and if thresholds are exceeded be sure to ask for confirmation — see the section “Cost estimation before generation”.
8. Do not pass secrets or the key in command arguments (except config --set-key).
9. On an API error, look at code: 401 — key, 402 — credits ran out, 422 — invalid input (check against velsvisual schema МОДЕЛЬ), 429 — rate limit (retry later), 451 — the API could not download the input image (re-upload via upload), 455 — maintenance, 500/501 — generation failed (see the error text; changing parameters often helps).

Cost estimation before generation (mandatory)

Before every real run (not --dry-run) complete the checklist:

1. Find out the model price in KIE credits (tokens). The first source is velsvisual pricing --search МОДЕЛЬ --json: the live kie.ai price list (24h cache), it returns the price in credits and in $ per generation. The label ≈ / approximate: true — the price was matched by description, not by exact id: this is an estimate, tell the user about it. The fallback source is docUrl from velsvisual models --search. Take the request parameters into account: the price often depends on duration, resolution, number of outputs and whether audio is present (a single model may have several price entries).
2. Recalculate into dollars. pricing already returns usd; for manual recalculation the guideline is 1 credit = $0.005, but check kie.ai/pricing, the rate may change.
3. Check against the balance: velsvisual credits.
4. Before launching, tell the user: the model, key parameters, the estimated cost in credits and in $, the current balance and what percentage of it the charge will be.
5. Be sure to ask for confirmation of the generation, if at least one of the following is true:
   • the estimated cost is more than $1;
   • the estimate is more than 10% of the current balance;
   • the model price could not be determined. Without an explicit "yes", do not send the request. If refused, suggest a cheaper option (model -fast/-mini, lower resolution/duration).

Typical pitfalls

• [500] output audio may be related to copyright restrictions with video models (Seedance and others with generate_audio): the model could not legally generate an audio track. Restart with --set generate_audio=false.
• A square image in 16:9 — models default to aspect_ratio: 16:9 and will crop the frame. To animate a finished image, set the aspect ratio of the source (--set aspect_ratio=1:1) or adaptive, if the model supports it.
• The image field is named differently: image_url, image_urls, input_urls, first_frame_url, image. --image will substitute the correct one itself; for manual --set check against the schema.
• More expensive ≠ better for a draft: first run a cheap/fast version of the model (-fast, -mini, 480p, short duration), and do the final render after approval.
• [451] — the API could not download your URL. Re-upload the file: velsvisual upload ФАЙЛ.

How to choose a model for the task

The user hasn't named a model — don't choose silently. Run velsvisual recommend <категория> --json: the command will return the 3–4 most popular families in the category, and for each — the latest (top) model version with the price in credits and $ and the tier (quality — maximum quality, balanced — balance, budget — cheap, for volume). Show the options to the user with prices and ask what matters more — quality or volume; only launch after their choice. Recommendations don't go stale: families and versions come from the live registry, prices — from the live kie.ai price list, so a new model in a family automatically appears in the output.

If the user named a task but manual search is needed:

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, эффекты

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

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

Animate a ready-made image (image-to-video)

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 is placed in whichever field the model actually has (first_frame_url, image_urls, …). Explicit two-step option: velsvisual upload ./sky.jpg → substitute the URL into --set ПОЛЕ=....

Text-to-music (Suno)

# простой режим: только промпт
velsvisual run suno --prompt "спокойный лоуфай для учёбы" \
  --wait --timeout 900 --download ./out --json

# custom mode: 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

In the response, each track has audioUrl (download it) and streamAudioUrl.

TTS (voiceover)

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

The list of available voices is in velsvisual schema elevenlabs/text-to-speech-turbo-2-5 (field voice, enum with voice ids).

Upscale

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

Checking a stuck task

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

A brand-new model (not yet in the catalog)

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

If the model is already in the catalog but appeared after the last cache update, run will update the registry itself — --api does not need to be specified.