Kie Media

When to Use

Works in Claude Code (/kie-media), Codex ($kie-media), Cursor (/kie-media in Agent chat) and Gemini CLI (auto-activated), or automatically whenever the request matches.

• The user wants a generated image or video (not a chart, not a screenshot, not an SVG icon you can hand-write).
• An asset is needed for a landing page, blog post, store listing, social post, demo data, or storyboard.
• The user asks to iterate on a previous generation (edit with a reference image).
• The user wants a voice-over / narration / TTS clip (kie speak), or wants a talking-head / lip-synced video from a still photo + audio, or from a video + a new audio track (kie lipsync).
• The user wants to upscale an image or remove its background (kie image topaz-upscale / kie image recraft-remove-bg).

Do not use it for: diagrams (use SVG/mermaid), UI mockups you can code, or anything the user did not ask to spend money on. Every call costs credits.

Critical Patterns

Model Choice

Prices are KIE list prices (Aug 30 2026 update, US$0.005/credit) and are pre-flight estimates only — the ledger settles on the real creditsConsumed. Video is billed per second: a 5 s 1080p Seedance clip is ~570 credits, well over the 200-credit default daily budget. Quote the cost before generating.

Code Examples

# 1. budget check
kie credits --json
# {"balance":980,"spentToday":16,"dailyBudget":200,"remainingToday":184}

# 2. draft image
kie image nano-banana-2 --prompt "flat illustration of a barista handing a coffee, teal palette" \
  --aspect 16:9 --out ./assets --name hero-barista --json
# {"taskId":"…","state":"success","creditsConsumed":8,"files":["assets/hero-barista.png"],…}

# 3. iterate with the draft as reference
kie image nano-banana-2 --prompt "same illustration, add a plant on the counter" \
  --ref "$(kie upload ./assets/hero-barista.png --json | jq -r .url)" --out ./assets --name hero-barista-v2 --json

# 4. only after the user approves: a clip, with an explicit ceiling
kie video kling-3.0 --prompt "the barista slides the cup across the counter, soft dolly-in" \
  --image "$(kie upload ./assets/hero-barista-v2.png --json | jq -r .url)" --duration 5 --max-credits 80 --out ./assets --json

Recipe: End-to-End Ad Spot (image → video → speak → lipsync)

# 1. hero image
kie image nano-banana-2 --prompt "product hero shot on a white studio backdrop" --out ./assets --name hero --json

# 2. animate it into a short clip
kie video seedance-2.5 --prompt "slow push-in on the product, soft studio lighting" \
  --image "$(kie upload ./assets/hero.png --json | jq -r .url)" --duration 5 --resolution 480p --max-credits 80 --out ./assets --json

# 3. voice-over script (small ceiling — no published price)
kie speak eleven-v2 --text "Introducing the product that changes everything." --voice Rachel \
  --max-credits 15 --out ./assets --name vo --json

# 4. lip-sync the clip to the new voice-over (small ceiling — no published price)
kie lipsync volcengine-lipsync \
  --video "$(kie upload ./assets/seedance-2-5.mp4 --json | jq -r .url)" \
  --audio "$(kie upload ./assets/vo.mp3 --json | jq -r .url)" \
  --max-credits 100 --out ./assets --name spot --json

Every local input (the animated clip, the generated voice-over) must go through kie upload first — models take URLs, not local paths. Check kie credits before step 3 and after step 4 to confirm real spend.

Handling outcomes:

exit 0 → report files[] and creditsConsumed to the user
exit 3 → tell the user the spend guard blocked it and quote the reason; ask before raising --max-credits or dailyBudget
exit 4 → task still running: `kie wait <taskId> --out <dir>` later
exit 1 → KIE failed the task (failMsg); failed tasks are not charged — rephrase the prompt or change model
exit 5 → API/auth issue; suggest `kie key check`

Commands

kie models --kind image|video|audio|lipsync   # catalog with supported flags
kie image <model> --prompt "…" [--ref url]... [--aspect 16:9] [--resolution 1K|2K|4K] [--out dir] [--name base]
kie video <model> --prompt "…" [--image url] [--end-image url] [--ref url]... [--duration s] [--resolution …] [--sound] [--fast] --max-credits N
kie speak <model> --text "…" --voice <name> --max-credits N       # kie speak eleven-v2 | eleven-turbo
kie lipsync <model> [--image url|--video url] --audio url [--prompt "…"] --max-credits N   # volcengine-lipsync | infinitalk | kling-avatar
kie run <model-id> --input '{…}' --max-credits N   # any Market model; verify schema on docs.kie.ai first
kie upload <file>                        # local file → temporary URL
kie status <taskId> | kie wait <taskId> --out dir
kie ledger                               # real spend log
kie config set dailyBudget 300           # only when the user asks

Resources

• CLI README: ../../kie/README.md
• Model catalog (flags → KIE input mapping): ../../kie/src/catalog.ts
• Request shapes reference: references/kie-api.md