sailtonight/kaloclip-skill

Creación de videos con IA Kaloclip (clip)

Kaloclip convierte información de productos e imágenes en un guión de video corto, y un guión en un video terminado. La cuenta es la que posee la clave API: sus créditos, su membresía Kaloclip (tamaño de la cola de videos, marca de agua en Gratis), sus activos de imagen y trabajos. La mayoría de los comandos son gratuitos. Los comandos [credits] envían trabajos pagados; consulte "Gastar créditos" antes de usarlos.

Ejecutar

La CLI se incluye dentro de esta skill (scripts/clip.py, solo stdlib de Python 3.11+ — nada que instalar):

python3 <directorio-de-esta-skill>/scripts/clip.py opciones

Todos los ejemplos a continuación escriben clip como abreviatura de python3 <directorio-de-esta-skill>/scripts/clip.py.

La salida es TOON (orientado a tokens) en stdout; agregue --json a cualquier comando para obtener JSON sin procesar. Los errores están estructurados en stdout con líneas help: procesables. Códigos de salida: 0 ok, 1 error, 2 uso.

Configuración — verifique esto antes de la primera llamada

Cada comando necesita una clave API de KaloData (enviada como el encabezado secret-key). Es la misma clave que usa la CLI kalo de la skill kalodata, almacenada en el mismo lugar. Antes de la primera llamada de una sesión, ejecute clip config y mire api_key. Si dice missing, deténgase — no adivine una clave y no lo intente de nuevo. Guíe al usuario a través de estos pasos y espere:

1. Obtener una clave — inicie sesión en https://www.kalodata.com/open-center/account y haga clic en generar clave. ¿Aún no tiene cuenta? Regístrese primero en https://www.kalodata.com/open-center/home.

2. Guardarla — clip config set --key <API_KEY> (almacenado en ~/.config/kalodata/config.toml, modo 0600, compartido con kalo), o configure KALODATA_API_KEY en el entorno.

3. Créditos — el mismo saldo de créditos que KaloData; se aplican los precios de Kaloclip y las reglas de membresía. clip credit muestra el saldo.

   llamada	créditos
   options, credit, product resolve, image upload/import, video preview, cualquier get / job	gratis
   script create	2
   video create	lo que dice video preview para el modelo/duración/resolución (ej. sd2 · 15s · 720P = 28)
   analysis create	el precio de Kaloclip para un análisis de guión

Comandos

comando	qué hace
clip options	modelos, duraciones, resoluciones disponibles en este momento; qué modelo permite qué duración
clip credit	créditos restantes
clip product resolve <enlace>	enlace de producto → título, categorías, puntos de venta, activos de imagen
clip image upload <archivo...>	1–6 imágenes locales (JPEG/PNG/GIF/WebP, ≤5MB) → ids de activos
clip image import <url...>	1–6 URLs de imágenes https públicas → ids de activos
clip script create	[credits] borrador de un guión; --product-link, o --image --title --category
clip script get <job_id>	estado del borrador y texto del guión; --wait
clip script candidates <job_id>	los dos candidatos de un trabajo de reescritura realizado en el sitio web de Kaloclip
clip video preview	créditos que costaría un video; --model --duration --resolution --ratio
clip video create	[credits] guión final → video; --script-job / --script-file / --script
clip video get <job_id>	estado del video; videoUrl cuando esté completado; --wait
clip analysis create <url_de_video>	[credits] desglose plano a plano de un video existente; --commerce --country
clip analysis get <job_id>	estado del análisis y resultado (conservado 30 días); --wait
clip job <job_id>	estado y salida de cualquier trabajo; --wait
clip config	mostrar/establecer clave (compartida con kalo) y endpoint (--base-url staging)

El flujo de video

1. clip options — elija --model y --duration juntos de su salida. Los modelos y sus duraciones cambian; nunca use un modelo de memoria.
2. Material del producto, ya sea:
   • clip product resolve <enlace> para verificar qué produce el enlace, luego pase el mismo --product-link a script create; o
   • las propias imágenes del usuario: clip image upload a.png b.jpg → --image ASSET_ID=IMAGE_URL (repetir, 1–6), más --title y --category.
3. Pregunte cómo debería sentirse el video (tono, escena, gancho) y pase eso como --description.
4. clip script create --product-link <enlace> --model <M> --duration <S> --description "..." → una ejecución de prueba. Muéstrelo, obtenga un sí, vuelva a ejecutar con --yes --idempotency-key <clave de la sugerencia> --wait (un borrador toma unos 30–60s; los créditos se cobran al enviar).
5. Muestre el guión. Para cambiarlo, escriba el texto editado en un archivo y use --script-file.
6. clip video create --script-job <job_id> [--script-file editado.txt] [--resolution 1080P] → una ejecución de prueba que incluye el costo de créditos. Obtenga un sí, vuelva a ejecutar con --yes --idempotency-key <clave>.
7. clip video get <job_id> --wait — un video de 15s toma unos 15 minutos (--wait sondea hasta 20). Dígale al usuario que se está ejecutando; si --wait agota el tiempo, sondee de nuevo — nunca lo vuelva a enviar. Entregue videoUrl (mp4) y coverImageUrl al usuario.

--script-job reutiliza las imágenes, título, modelo y duración con los que se envió el borrador cuando se hizo en esta máquina; de lo contrario, pase nuevamente (--product-link cubre la mayor parte).

Gastar créditos

Los comandos [credits] nunca actúan en la primera ejecución: sin --yes imprimen la solicitud exacta (dry_run:), su costo de créditos y una clave de idempotencia, y no envían nada. Muéstrelo al usuario, obtenga un sí explícito, luego vuelva a ejecutar con --yes --idempotency-key <clave>. Nunca agregue --yes por su cuenta, y nunca repita envíos.

• Reintentar: si un envío termina con "resultado desconocido" (tiempo de espera / 5xx / SUBMISSION_IN_PROGRESS), vuelva a ejecutar el comando idéntico con la misma --idempotency-key dentro de 5 minutos — Kaloclip devuelve el trabajo original sin cobrar de nuevo. Una nueva clave significa un nuevo trabajo pagado. SUBMISSION_OUTCOME_UNKNOWN: deténgase y dígaselo al usuario; no lo vuelva a enviar.
• Los trabajos son asíncronos: guarde el id del trabajo; sondee con --wait (cada 5s). Nunca vuelva a enviar un trabajo que esté queued o processing.
• TASK_QUEUE_FULL: la cola de videos de la membresía está llena (Gratis: un video a la vez). No se cobró nada; espere el video en ejecución, luego envíe de nuevo.
• RATE_LIMIT_EXCEEDED: límites por usuario (subidas/importaciones 10/min, resolución de producto 10/min, vista previa 20/min, videos 5/min) — espere al menos 60 segundos.

Análisis de guión

clip analysis create <url de tiktok|kalodata|youtube-shorts> descompone un video en escenas (video_scripts[]: tiempo, plano, descripción visual, voz en off, cada uno con una traducción), más género del presentador, idioma hablado, movimientos de cámara y por qué funciona. Videos de TikTok comprables: agregue --commerce --country US. Los resultados permanecen legibles durante 30 días (clip analysis get <job_id>); agregue --json para cada campo. Úselo para aprender de un video viral antes de redactar su propio guión.

Leer los datos correctamente

• El guión de un borrador completado es una dirección de formato largo (talento, estilo, escena, VISUAL / AUDIO / ACCIÓN DEL TALENTO por escena). Muéstrelo completo; no lo resuma antes de que el usuario lo apruebe.
• video preview es una estimación; un envío aún puede ser rechazado (cola, membresía, entradas).
• videoUrl es el archivo terminado; los videos de membresía Gratis llevan una marca de agua.
• selling_points de product resolve puede estar vacío mientras Kaloclip aún analiza el producto; vuelva a ejecutar en un minuto o continúe sin ellos.
• Los activos de imagen pertenecen a la cuenta; los ids de activos de una clave no funcionan con otra.