kie cli
EN GitHub

Open source · MIT · 0 dependencias en runtime

Generamedios.Conservatusllaves.

Una herramienta de línea de comandos para que los agentes de IA creen imágenes y video en KIE.ai — sin entregarles nunca la API key, y con un techo duro a lo que puede gastar una sola ejecución.

Empezar → Leer la documentación
$ git clone https://github.com/julio-daza/kie-cli.git && cd kie-cli/kie && npm i && npm run build && npm link
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 dependencias en runtime
2 hosts con los que habla — ambos de KIE
40 tests, sin red
3 chequeos de gasto antes de cada request

Por qué otra CLI

Construida para lo único que otros wrappers hacen mal: la llave cuesta dinero.

Las APIs de medios son las credenciales más caras de perder. La mayoría de integraciones leen la key de una variable de entorno, arrastran cientos de paquetes y traen un webhook por defecto. kie no hace nada de eso.

01

Key en el llavero

Se guarda en el Keychain de macOS (archivo 0600 en otros sistemas). Las variables de entorno requieren opt-in explícito. Toda la salida pasa por un redactor.

02

Sin salidas a terceros

Solo habla con api.kie.ai y el host de subida de KIE. Nunca envía callBackUrl — los resultados se consultan por polling, nada de tus generaciones se empuja a ningún lado.

03

Guardia de gasto, antes del request

Tope por tarea, presupuesto diario calculado con los créditos reales que reporta KIE y chequeo de saldo. Bloqueado significa que nada salió de tu máquina.

04

Contrato nativo para agentes

JSON en stdout, mensajes en stderr, códigos de salida para bifurcar. Tablas legibles cuando lo ejecuta un humano en la terminal.

05

Cero dependencias

Solo built-ins de Node ≥ 20. El código que toca tu key son ~700 líneas que puedes leer antes de confiarle nada.

06

Siempre descarga

Las URLs de resultado de KIE expiran en 24 horas. kie escribe archivos a disco y devuelve rutas, nunca enlaces.

Instalación

Dos minutos, bien hechos.

  1. 01

    Clona y enlaza

    Solo dependencias de desarrollo (TypeScript). npm link deja kie en tu PATH.

    git clone https://github.com/julio-daza/kie-cli.git
cd kie-cli/kie
npm install && npm run build && npm link
  2. 02

    Crea una key dedicada

    En kie.ai/api-key crea una key solo para agentes y ponle topes por hora/día más una lista blanca de IPs. KIE los aplica aunque alguien se salte esta CLI.

    # https://kie.ai/api-key → nueva key → topes + IP whitelist
  3. 03

    Guárdala y verifícala

    La entrada está oculta. La key va al llavero y no vuelve a aparecer en ninguna salida.

    kie key set
kie key check

Uso

Un comando por trabajo.

kie image nano-banana-2 \
  --prompt "cafetería isométrica, luz cálida" \
  --aspect 16:9 --resolution 2K --out ./assets
Lo que vuelve 
{
  "taskId": "task_c0ffee12",
  "model": "nano-banana-2",
  "state": "success",
  "creditsConsumed": 8,
  "files": ["kie-media/nano-banana-2-c0ffee12.png"]
}

Guardia de gasto

Bloqueado significa que no se envió nada.

KIE no publica precios por modelo en su documentación de API, así que kie no adivina. Apila tres chequeos independientes y rechaza con código de salida 3 si alguno falla.

Códigos de salida
0 éxito
1 la tarea falló del lado de KIE
2 error de uso
3 bloqueado por la guardia de gasto
4 tiempo agotado — la tarea sigue corriendo, retoma con kie wait
5 error de API / autenticación
01

Tope por tarea

Los modelos con precio verificado se comparan contra maxCreditsPerTask. Todo lo demás exige un --max-credits explícito — el agente tiene que decir en voz alta cuánto acepta gastar.

02

Presupuesto diario

Un ledger local registra cada tarea; al completarse se escribe el creditsConsumed real. Las tareas pendientes cuentan por su tope, así una ráfaga no se pasa.

03

Saldo

Si la estimación supera lo que queda en la cuenta, el request nunca sale.

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

Documentación

Comandos

kie key set|check|deleteGuardar la API key (Keychain / archivo 0600), verificarla, eliminarla.
kie creditsSaldo más el gasto de hoy contra el presupuesto diario.
kie models [--kind image|video]Catálogo curado con los flags que soporta cada modelo.
kie image <modelo> --prompt … [opts]Generar una imagen, esperar, descargar.
kie video <modelo> --prompt … [opts]Generar un video, esperar, descargar.
kie run <model-id> --input '{…}' --max-credits NVía de escape para cualquier modelo del Market de KIE.
kie status <taskId>Una consulta, sin descarga.
kie wait <taskId> [--out dir]Consultar hasta terminar, descargar, cerrar el ledger.
kie upload <archivo>Archivo local → URL temporal para --ref / --image (KIE lo borra a los ~3 días).
kie ledger [--limit 20]Registro local de gasto con creditsConsumed reales.
kie config set <clave> <valor>dailyBudget · maxCreditsPerTask · outDir · pollSeconds · waitTimeoutSeconds

Flags de generación

--prompt <texto>El prompt.
--ref <url>Imagen de referencia, repetible (edición / estilo / referencia multimodal).
--image <url> / --end-image <url>Primer y último frame para video.
--aspect, --resolution, --duration16:9 · 1K|2K|4K|720p · segundos
--sound, --fast, --formatAudio nativo · variante barata · png|jpg
--set clave=valorCampo crudo del modelo, repetible. callBackUrl se rechaza.
--max-credits <n>Aceptar gastar hasta n créditos en esta tarea.
--dry-runImprime el request exacto, no envía nada.
--out <dir>, --name <base>, --no-waitDónde van los archivos · nombre base · enviar y volver.
--json, --pretty, --no-color, --quietControl de salida. JSON es automático al hacer pipe.

Catálogo

nano-banana-2 imagen Google Nano Banana 2 — genera + edita con hasta 14 referencias. Est. 1K=8 · 2K=12 · 4K=18 créditos.
seedream-v4 imagen ByteDance Seedream V4 — texto a imagen, pasa a edición con --ref.
kling-3.0 video Kling 3.0 — 3–15 s, audio nativo, --set mode=pro.
seedance-2.5 video ByteDance Seedance 2.5 — frames o referencias multimodales, 4–30 s.
minimax-h3 video MiniMax H3 — elige el submodelo según tus flags (texto / imagen / referencia).
veo3 video Google Veo 3 — endpoint propio, --fast para veo3_fast.

Referencia completa en el README →

Skill de agente

Enséñale la etiqueta a tu agente.

El repo incluye un skill para Claude Code (spec Agent Skills). Le dice al agente cuándo generar, qué modelo elegir, que revise el presupuesto primero, que siempre pase --max-credits en video y que devuelva rutas de archivo — nunca URLs.

ln -s "$PWD/skill/kie-media" ~/.claude/skills/kie-media
  • ✓Revisar kie credits antes de la primera generación.
  • ✓Primero imágenes; video solo cuando el usuario aprueba el look.
  • ✓Exit 3 → reportar la razón, nunca reintentar con un tope mayor por su cuenta.
  • ✓Nunca pedir, mostrar ni configurar la API key.

Preguntas frecuentes

¿Está afiliado a KIE.ai?

No. Es un proyecto independiente de la comunidad. KIE y su logo son marcas de su propietario, usadas solo para identificar el servicio.

¿Funciona en Linux o Windows?

Sí. Sin Keychain, la key se guarda en ~/.config/kie/key con permisos 0600. Todo lo demás es idéntico.

¿Por qué todavía no hay paquete en npm?

Llegará cuando los flags se estabilicen, publicado desde CI con provenance para que el tarball sea verificable contra el commit. Mientras tanto: clone + npm link.

¿Y si un modelo no está en el catálogo?

kie run <model-id> --input '{…}' --max-credits N envía cualquier modelo del Market de KIE. Revisa el schema en docs.kie.ai primero, o usa --dry-run.

¿Puedo usarlo sin un agente?

Claro. En la terminal muestra tablas, paneles y un spinner en vivo; si haces pipe obtienes JSON.

Daleatusagentesunacámara,notubilletera.

Licencia MIT. Lee el código antes de confiarle una key — de eso se trata.

Ver en GitHub →