One CLI & MCP for
200+ AI models.
Give Claude Code, Cursor, Codex, and Gemini CLI live KIE schemas, per-task catalog price checks, and zero-dependency media generation—straight from your repo.
export KIE_API_KEY="your_api_key"
npx skills add https://kie.aiClaude Code
Auto-discovered via npx skills + /claude/v1/messages
Cursor & Windsurf
Local non-blocking stdio MCP server (6 tools)
OpenAI Codex CLI
Skills + /codex/v1/responses wire support
Gemini CLI
Skills + native /gemini/v1beta streaming
Works where you already write code.
Pick your coding agent or IDE below. Terminal agents load SKILL.md on demand; desktop apps connect to kie-cli.mjs mcp over standard input/output.
Install once per project or globally with -g. Claude Code automatically loads kie-models when you ask for images, videos, audio, or model pricing.
$ npx skills add https://kie.ai
> Generate a 16:9 hero banner for a matte black GaN desktop charger
using Kling Image 4.0 at 2k under 15 credits, save to ./public/hero.png
● Skill(kie-models)
├─ node kie-cli.mjs doc kling-4-0/image
├─ node kie-cli.mjs run kling-4-0/image \
--max-credits 15 \
--input '{"prompt":"Matte black GaN desktop charger...","resolution":"2k","aspect_ratio":"16:9"}' \
--out ./public/hero.png
└─ ✓ Saved ./public/hero.png (taskId: 0ba8c332…, 11.3 credits)Pre-flight price checks & timeout-safe MCP.
Autonomous agents retry aggressively and pass unvalidated paths unless the tool layer enforces clear boundaries. kie-cli.mjs builds three safeguards into the runtime:
Per-task catalog price check (--max-credits)
Narrows live catalog rows by your input hints (resolution, mode, duration, count) and checks the conservative upper bound before calling createTask. Exits locally with code 3 if exceeded.
Non-blocking stdio & two-phase 20s polling
Answers host ping checks concurrently and returns { taskId, state: "generating" } within 20s on long video jobs—staying inside typical ~60s desktop tool timeouts so the agent polls kie_task_status instead of resubmitting.
Workspace-jailed downloads (wx)
MCP outPath is resolved with fs.realpathSync inside KIE_OUTPUT_DIR prior to task creation and written with flag: "wx" so existing files are never overwritten.
$ node kie-cli.mjs run veo-3-1 \
--input '{"prompt":"Aerial coastline","mode":"Quality-4k"}' \
--max-credits 50
[kie] Error: Per-task price check blocked request:
"veo-3-1" can cost up to 400 credits in the catalog
for these parameters, which exceeds --max-credits 50.
Nothing was sent.
$ echo $?
3
# Switch to Lite-1080p (35 credits <= 50) -> proceeds cleanly:
$ node kie-cli.mjs run veo-3-1 \
--input '{"prompt":"Aerial coastline","mode":"Lite-1080p"}' \
--max-credits 50 --out ./coast.mp4
✓ Saved ./coast.mp4 (35 credits)Every command on one screen.
Requires Node.js 18+ with zero external packages. Exit codes: 0 ok, 1 API / runtime error, 2 invalid flag, 3 --max-credits pre-flight block.
- KIE_API_KEY
- Bearer token from kie.ai/api-key
- KIE_MAX_CREDITS
- Default per-task catalog ceiling for CLI & MCP
- KIE_OUTPUT_DIR
- Sandbox directory for MCP file writes (defaults to cwd)
| Subcommand | Behavior |
|---|---|
| list [--task T] [--provider P] [--q kw] [--json] | Query live models on KIE (uses /api/v1/models with key, or public catalog without key). |
| doc <model_id_or_slug> | Print inline OpenAPI 3.1 JSON schema or /model/<slug>.md parameter specification. |
| price [keyword] [--json] | Query live catalog credit & USD unit prices (no API key required). |
| balance [--json] | Read remaining credits on KIE_API_KEY via GET /api/v1/chat/credit. |
| run <model_id> --input '{...}' [--max-credits N] [--out path] | Pre-check catalog upper bound, submit createTask, poll recordInfo, and download output. |
| status <task_id> [--wait sec] [--out path] | Check or resume polling an existing taskId without resubmitting. |
| mcp | Start non-blocking JSON-RPC 2.0 stdio MCP server (6 tools for Cursor / Claude Desktop). |
Frequently asked questions.
Explore individual model endpoints in the API Market or compare unit rates on Pricing.
How do I set up the KIE MCP Server in Cursor, Windsurf, or Claude Desktop?
+
Download kie-cli.mjs (via npx skills add https://kie.ai -g or curl -fsSL https://kie.ai/cli/kie-cli.mjs -o ~/.kie/kie-cli.mjs) and add "command": "node" with args ["/path/to/kie-cli.mjs", "mcp"] and env KIE_API_KEY in mcp.json or claude_desktop_config.json. It runs locally over stdio with zero npm dependencies and exposes kie_list_models, kie_model_spec, kie_pricing, kie_credit_balance, kie_submit_task, and kie_task_status.
What is the difference between Agent Skills and the Local MCP Server?
+
Agent Skills (npx skills add https://kie.ai) drop compact SKILL.md instructions and kie-cli.mjs into .agents/skills/ for terminal-enabled coding agents like Claude Code, Codex CLI, and Gemini CLI—using zero context tokens until invoked. The stdio MCP Server (node kie-cli.mjs mcp) exposes typed JSON-RPC tools for desktop apps like Claude Desktop, Cursor, and Windsurf when shell execution is sandboxed.
How does the --max-credits per-task price check work?
+
Before calling createTask, --max-credits <N> (or KIE_MAX_CREDITS) queries live KIE catalog prices, narrows matching tiers using your input parameters (such as resolution, mode, duration, and image count), and checks the conservative upper bound (Math.max). If the catalog upper bound exceeds N—or if no catalog price can be verified—kie-cli.mjs exits locally with code 3 before sending the task. For account-wide key limits, configure Safe Spend on the API Keys page.
How does the MCP server avoid 60-second desktop tool timeouts on video generation?
+
kie_submit_task caps inline polling at 20 seconds. Fast image tasks return their finished output URLs directly, while longer video or music jobs return { taskId, state: "generating" } before any desktop host timeout fires, instructing the agent to poll kie_task_status(taskId) rather than resubmitting a duplicate paid task.
Where can LLMs read KIE documentation in plain Markdown?
+
Point any LLM or agent at https://kie.ai/llms.txt for the top-level CLI, Skills, and MCP index, or fetch https://kie.ai/model/{slug}.md (for example, https://kie.ai/model/kling-4-0/image.md) for any individual model’s Markdown specification. Every model page header also includes a single-click "Use with Agent / CLI" button with Copy .md and View .md shortcuts.