Open source · MIT · 0 runtime dependencies

Generatemedia.Keepyourkeys.

A command-line tool that lets AI agents create images and video on KIE.ai — without ever handing them the API key, and with a hard ceiling on what a single run can spend.

Get started → Read the docs

$ npm i -g @uxdata-co/kie

kie help

            ╭─●─╮                
           ╱     ╲               
          ╱  ╱╲   ╲              kie v0.2.0
         ╱  ╱  ╲ ╲ ╲             KIE.ai media generation for agents & humans
        ╱  ╱────╲ ╲ ╲            images · video · zero dependencies · spend-guarded
       ╱  ╱      ╲   ╲           
  ●───╯  ╱        ╲ ╲ ╰───●      

$ kie credits
╭─ ▲ kie  credits ──────────────────────────────────╮
│  balance          980 credits  ≈ US$4.90          │
│  today            16 / 200  ████████████████████████ 8%  │
│  remaining today  184 credits                    │
╰──────────────────────────────────────────────────────╯

$ kie image nano-banana-2 --prompt "isometric coffee shop" --aspect 16:9
⠹ nano-banana-2  generating 40%  task_c0ffee12 14s
╭─ ▲ kie  generation complete ────────────────────────╮
│  state    success                                   │
│  credits  8                                         │
│  files    kie-media/nano-banana-2-c0ffee12.png      │
╰──────────────────────────────────────────────────────╯

0 runtime dependencies

2 hosts it talks to — both KIE's

40 tests, no network

3 spend checks before every request

Why another CLI

Built for the one thing other wrappers get wrong: the key is paid.

Media APIs are the most expensive credentials to leak. Most integrations read the key from an env var, pull in hundreds of packages and ship a default webhook. kie does none of that.

Key in the keychain

Stored in macOS Keychain (0600 file elsewhere). Env vars need an explicit opt-in. Every byte of output goes through a redactor.

No third-party egress

Talks only to api.kie.ai and KIE's upload host. Never sends a callBackUrl — results are polled, nothing about your generations is pushed anywhere.

Spend guard, before the request

Per-task cap, a daily budget computed from the real credits KIE reports, and a balance check. Blocked means nothing left your machine.

Agent-native contract

JSON on stdout, messages on stderr, exit codes you can branch on. Pretty tables when a human runs it in a terminal.

Zero dependencies

Node ≥ 20 built-ins only. The code that touches your key is ~700 lines you can read before trusting it.

Always downloads

KIE result URLs expire in 24 hours. kie writes files to disk and hands back paths, never links.

Install

Two minutes, done right.

01
Install from npm

Node ≥ 20. Published from GitHub Actions with provenance — npm audit signatures verifies the tarball came from the repo.
```
npm i -g @uxdata-co/kie
kie version
```
02
Create a dedicated key

At kie.ai/api-key, make a key just for agents and set hourly/daily caps plus an IP whitelist. KIE enforces those even if this CLI is bypassed.
```
# https://kie.ai/api-key → new key → caps + IP whitelist
```
03
Store it, verify it

Input is hidden. The key goes to the Keychain and never appears in output again.
```
kie key set
kie key check
```

Usage

One command per job.

kie image nano-banana-2 \
  --prompt "isometric coffee shop, warm light" \
  --aspect 16:9 --resolution 2K --out ./assets

kie video kling-3.0 \
  --prompt "drone shot over a fjord at dawn" \
  --duration 5 --sound --max-credits 80

kie upload ./sketch.png          # → temporary URL
kie image nano-banana-2 \
  --prompt "same scene at night" \
  --ref https://…/sketch.png

kie run some-vendor/some-model \
  --input '{"prompt":"…"}' --max-credits 30

What comes back

{
  "taskId": "task_c0ffee12",
  "model": "nano-banana-2",
  "state": "success",
  "creditsConsumed": 8,
  "files": ["kie-media/nano-banana-2-c0ffee12.png"]
}

Tutorials

Generate images from chat.

This is the whole point: your coding agent makes the media, you keep the key. One install, one skill, then you just ask.

Once, for any agent

Install the CLI

npm i -g @uxdata-co/kie

Store the key — it never reaches the agent

kie key set

Install the kie-media skill

kie skill install        # Claude Code + Codex
kie skill install --agent codex   # just one

Prefer the skills CLI? npx skills add julio-daza/kie-cli does the same for any supported agent.

1
Start a new session — skills are discovered at startup. CLI, desktop app and IDE extension all read ~/.claude/skills/.
2
Ask in plain language. The description triggers the skill; /kie-media invokes it explicitly.
3
Claude checks the budget, generates, downloads, and answers with the file path and credits spent.

youGenerate a 16:9 hero image of an isometric coffee shop with warm light, for the landing page.

Claude Code

$ kie credits --json

$ kie image nano-banana-2 --prompt "isometric coffee shop, warm light" --aspect 16:9 --out ./assets --name hero-coffee --json

Done — 8 credits. Saved to assets/hero-coffee.png (1920×1080). Want a night version with the same composition?

1
Start a new session — CLI, IDE extension and desktop app all read ~/.agents/skills/. /skills lists what is installed.
2
Ask naturally, or call it with $kie-media. For video, say the cap out loud.
3
Codex runs the CLI with --json and reports the file path; a blocked request (exit 3) comes back with the reason.

you$kie-media make a 5-second clip of the barista sliding a cup across the counter, soft dolly-in. Cap it at 80 credits.

Codex

$ kie upload ./assets/hero-coffee.png --json

$ kie video kling-3.0 --prompt "barista slides a cup across the counter, soft dolly-in" --image <url> --duration 5 --sound --max-credits 80 --json

Kling 3.0, 5 s with sound — 64 credits. Saved to assets/barista-slide.mp4. Exit 0; 120 credits left today.

What the agent will and won't do

✓Images first; video only after you approve the look, always with --max-credits.
✓A spend-guard block (exit 3) is reported with its reason — it never raises the cap by itself.
✓It never asks for, prints or sets the API key. Missing key → it tells you to run kie key set.
✓You get a file path, never a KIE URL (they expire in 24 h).

Daily ceiling for everything the agent does: kie config set dailyBudget 300

Spend guard

Blocked means nothing was sent.

KIE doesn't publish per-model prices in its API docs, so kie doesn't guess. It layers three independent checks and refuses with exit code 3 if any fails.

Exit codes

0	success
1	task failed on KIE's side
2	usage error
3	blocked by the spend guard
4	timed out — task still running, resume with kie wait
5	API / auth error

Per-task cap

Models with a verified price are compared against maxCreditsPerTask. Everything else requires an explicit --max-credits — the agent has to say out loud how much it accepts to spend.

Daily budget

A local ledger records every task; when it completes, the real creditsConsumed is written back. Pending tasks count at their cap, so a burst can't overshoot.

Balance

If the estimate exceeds what's left on the account, the request never leaves.

exit 3

$ kie video kling-3.0 --prompt "drone shot over a fjord"
✖ Spend guard blocked the request: This model has no known credit
  estimate. Re-run with --max-credits <n> to state the most you accept
  to spend on this task.
Today: 16 credits used, 184 remaining. Balance: 980.
$ echo $?
3

Documentation

Commands

kie key set\|check\|delete	Store the API key (Keychain / 0600 file), verify it, remove it.
kie credits	Balance plus today's spend against the daily budget.
kie models [--kind image\|video]	Curated catalog with the flags each model supports.
kie image <model> --prompt … [opts]	Generate an image, wait, download.
kie video <model> --prompt … [opts]	Generate a video, wait, download.
kie run <model-id> --input '{…}' --max-credits N	Escape hatch for any KIE Market model.
kie status <taskId>	One poll, no download.
kie wait <taskId> [--out dir]	Poll until done, download, settle the ledger.
kie upload <file>	Local file → temporary URL for --ref / --image (KIE deletes it after ~3 days).
kie ledger [--limit 20]	Local spend log with real creditsConsumed.
kie config set <key> <value>	dailyBudget · maxCreditsPerTask · outDir · pollSeconds · waitTimeoutSeconds
kie skill install [--agent claude\|codex\|all]	Install the kie-media agent skill for Claude Code / Codex (--project for the current repo).

Generation flags

--prompt <text>	The prompt.
--ref <url>	Reference image, repeatable (edit / style / multimodal reference).
--image <url> / --end-image <url>	First and last frame for video.
--aspect, --resolution, --duration	16:9 · 1K\|2K\|4K\|720p · seconds
--sound, --fast, --format	Native audio · cheaper variant · png\|jpg
--set key=value	Raw model field, repeatable. callBackUrl is rejected.
--max-credits <n>	Accept spending up to n credits on this task.
--dry-run	Print the exact request, send nothing.
--out <dir>, --name <base>, --no-wait	Where files go · base filename · submit and return.
--json, --pretty, --no-color, --quiet	Output control. JSON is automatic when piped.

Catalog

nano-banana-2	image	Google Nano Banana 2 — generate + edit with up to 14 refs. Est. 1K=8 · 2K=12 · 4K=18 credits.
seedream-v4	image	ByteDance Seedream V4 — text-to-image, switches to edit with --ref.
kling-3.0	video	Kling 3.0 — 3–15 s, native audio, --set mode=pro.
seedance-2.5	video	ByteDance Seedance 2.5 — frames or multimodal refs, 4–30 s.
minimax-h3	video	MiniMax H3 — sub-model chosen from your flags (text / image / reference).
veo3	video	Google Veo 3 — own endpoint, --fast for veo3_fast.

Full reference in the README →

Agent skill

Teach your agent the etiquette.

The package ships an agent skill (Agent Skills spec) for Claude Code and Codex. It tells the agent when to generate, which model to pick, to check the budget first, to always pass --max-credits on video, and to return file paths — never URLs.

kie skill install            # ~/.claude/skills + ~/.agents/skills
npx skills add julio-daza/kie-cli   # alternative

✓Check kie credits before the first generation.
✓Images first, video only after the user approves the look.
✓Exit 3 → report the reason, never retry with a bigger cap on its own.
✓Never ask for, echo or set the API key.

FAQ

Is this affiliated with KIE.ai?

No. It's an independent, community project. KIE and its logo are trademarks of their owner, used only to identify the service.

Does it work on Linux or Windows?

Yes. Without a Keychain the key is stored in ~/.config/kie/key with 0600 permissions. Everything else is identical.

How is the npm package built?

Every release is published by GitHub Actions from a git tag, with npm provenance: the tarball is cryptographically linked to the commit and workflow that produced it. Zero runtime dependencies, so what you audit is what runs.

What if a model isn't in the catalog?

kie run <model-id> --input '{…}' --max-credits N sends any KIE Market model. Check the schema on docs.kie.ai first, or use --dry-run.

Can I use it without an agent?

Of course. In a terminal it renders tables, panels and a live spinner; pipe it and you get JSON.

Giveyouragentsacamera,notyourwallet.

MIT licensed. Read the source before you trust it with a key — that's the point.

View on GitHub →

Generatemedia.Keepyourkeys.Generatemedia.Keepyourkeys.