sailtonight/kaloclip-skill

Création vidéo AI Kaloclip (clip)

Kaloclip transforme les informations et images d'un produit en script vidéo courte, puis un script en vidéo finie. Le compte est celui qui possède la clé API : ses crédits, son abonnement Kaloclip (taille de file d'attente vidéo, filigrane sur Free), ses ressources images et ses tâches. La plupart des commandes sont gratuites. Les commandes [credits] soumettent des tâches payantes — voir « Dépenser des crédits » avant de les utiliser.

Exécution

Le CLI est fourni dans cette compétence (scripts/clip.py, Python 3.11+ stdlib uniquement — rien à installer) :

python3 <dossier-compétence>/scripts/clip.py options

Tous les exemples ci-dessous utilisent clip comme raccourci pour python3 <dossier-compétence>/scripts/clip.py.

La sortie est TOON (orientée tokens) sur stdout ; ajoutez --json à n'importe quelle commande pour du JSON brut. Les erreurs sont structurées sur stdout avec des lignes help: exploitables. Codes de sortie : 0 ok, 1 erreur, 2 utilisation.

Configuration — vérifiez ceci avant le premier appel

Chaque commande a besoin d'une clé API KaloData (envoyée comme en-tête secret-key). C'est la même clé que celle utilisée par le CLI kalo de la compétence kalodata, stockée au même endroit. Avant le premier appel d'une session, exécutez clip config et regardez api_key. Si elle indique missing, arrêtez-vous — ne devinez pas de clé et ne réessayez pas. Guidez l'utilisateur à travers ces étapes et attendez :

1. Obtenir une clé — connectez-vous sur https://www.kalodata.com/open-center/account et cliquez sur générer une clé. Pas encore de compte ? Inscrivez-vous d'abord sur https://www.kalodata.com/open-center/home.

2. Enregistrez-la — clip config set --key <CLÉ_API> (stockée dans ~/.config/kalodata/config.toml, mode 0600, partagée avec kalo), ou définissez KALODATA_API_KEY dans l'environnement.

3. Crédits — le même solde de crédits que KaloData ; les prix et règles d'abonnement Kaloclip s'appliquent. clip credit affiche le solde.

   appel	crédits
   options, credit, product resolve, image upload/import, video preview, tout get / job	gratuit
   script create	2
   video create	ce que video preview indique pour le modèle/durée/résolution (ex. sd2 · 15s · 720P = 28)
   analysis create	le prix Kaloclip pour une analyse de script

Commandes

commande	quoi
clip options	modèles, durées, résolutions disponibles actuellement ; quel modèle permet quelle durée
clip credit	crédits restants
clip product resolve <lien>	lien produit → titre, catégories, arguments de vente, ressources images
clip image upload <fichier...>	1–6 images locales (JPEG/PNG/GIF/WebP, ≤5Mo) → identifiants de ressource
clip image import <url...>	1–6 URL d'images https publiques → identifiants de ressource
clip script create	[credits] rédiger un script ; --product-link, ou --image --title --category
clip script get <id_tâche>	état de l'ébauche et texte du script ; --wait
clip script candidates <id_tâche>	les deux candidats d'une tâche de réécriture faite sur le site web Kaloclip
clip video preview	crédits qu'une vidéo coûterait ; --model --duration --resolution --ratio
clip video create	[credits] script final → vidéo ; --script-job / --script-file / --script
clip video get <id_tâche>	état de la vidéo ; videoUrl une fois terminée ; --wait
clip analysis create <url_vidéo>	[credits] décomposition plan par plan d'une vidéo existante ; --commerce --country
clip analysis get <id_tâche>	état et résultat de l'analyse (conservé 30 jours) ; --wait
clip job <id_tâche>	état et sortie de n'importe quelle tâche ; --wait
clip config	afficher/définir la clé (partagée avec kalo) et le point d'accès (--base-url staging)

Le flux vidéo

1. clip options — choisissez --model et --duration ensemble à partir de sa sortie. Les modèles et leurs durées changent ; n'utilisez jamais un modèle de mémoire.
2. Matériel produit, soit :
   • clip product resolve <lien> pour vérifier ce que le lien produit, puis passez le même --product-link à script create ; ou
   • les propres images de l'utilisateur : clip image upload a.png b.jpg → --image ID_RESSOURCE=URL_IMAGE (répéter, 1–6), plus --title et --category.
3. Demandez ce que la vidéo devrait donner comme ressenti (ton, scène, accroche) et passez-le comme --description.
4. clip script create --product-link <lien> --model <M> --duration <S> --description "..." → un avant-goût. Montrez-le, obtenez un oui, relancez avec --yes --idempotency-key <clé du hint> --wait (une ébauche prend environ 30–60s ; les crédits sont débités à la soumission).
5. Montrez le script. Pour le modifier, écrivez le texte édité dans un fichier et utilisez --script-file.
6. clip video create --script-job <id_tâche> [--script-file edited.txt] [--resolution 1080P] → un avant-goût qui inclut le coût en crédits. Obtenez un oui, relancez avec --yes --idempotency-key <clé>.
7. clip video get <id_tâche> --wait — une vidéo de 15s prend environ 15 minutes (--wait interroge jusqu'à 20). Dites à l'utilisateur qu'elle est en cours ; si --wait expire, interrogez à nouveau — ne soumettez jamais à nouveau. Transmettez videoUrl (mp4) et coverImageUrl à l'utilisateur.

--script-job réutilise les images, le titre, le modèle et la durée avec lesquels l'ébauche a été soumise lorsque l'ébauche a été faite sur cette machine ; sinon, repassez-les (--product-link couvre la plupart).

Dépenser des crédits

Les commandes [credits] n'agissent jamais au premier lancement : sans --yes, elles affichent la requête exacte (dry_run:), son coût en crédits et une clé d'idempotence, et n'envoient rien. Montrez-la à l'utilisateur, obtenez un oui explicite, puis relancez avec --yes --idempotency-key <clé>. N'ajoutez jamais --yes de votre propre chef et ne bouclez jamais les soumissions.

• Réessayer : si une soumission se termine par « outcome is unknown » (timeout / 5xx / SUBMISSION_IN_PROGRESS), relancez la commande identique avec la même --idempotency-key dans les 5 minutes — Kaloclip retourne alors la tâche originale au lieu de facturer à nouveau. Une nouvelle clé signifie une nouvelle tâche payante. SUBMISSION_OUTCOME_UNKNOWN : arrêtez et informez l'utilisateur ; ne soumettez pas à nouveau.
• Les tâches sont asynchrones : conservez l'ID de la tâche ; interrogez avec --wait (toutes les 5s). Ne soumettez jamais à nouveau une tâche qui est queued ou processing.
• TASK_QUEUE_FULL : la file d'attente vidéo de l'abonnement est pleine (Free : une vidéo à la fois). Rien n'a été débité ; attendez la fin de la vidéo en cours, puis soumettez à nouveau.
• RATE_LIMIT_EXCEEDED : limites par utilisateur (téléchargements/importations 10/min, résolution produit 10/min, prévisualisation 20/min, vidéos 5/min) — attendez au moins 60 secondes.

Analyse de script

clip analysis create <url tiktok|kalodata|youtube-shorts> décompose une vidéo en scènes (video_scripts[] : temps, échelle de plan, description visuelle, voix-off, chacune avec une traduction), plus le genre du présentateur, la langue parlée, les mouvements de caméra et pourquoi ça fonctionne. Vidéos TikTok achetables : ajoutez --commerce --country US. Les résultats restent lisibles pendant 30 jours (clip analysis get <id_tâche>) ; ajoutez --json pour tous les champs. Utilisez-le pour apprendre d'une vidéo virale avant de rédiger votre propre script.

Lire les données correctement

• Le script d'une ébauche terminée est une direction longue (talent, style, scène, par scène VISUEL / AUDIO / ACTION DU TALENT). Montrez-le en entier ; ne le résumez pas avant que l'utilisateur n'ait approuvé.
• video preview est une estimation ; une soumission peut encore être refusée (file d'attente, abonnement, entrées).
• videoUrl est le fichier final ; les vidéos d'abonnement Free portent un filigrane.
• selling_points de product resolve peut être vide pendant que Kaloclip analyse encore le produit — relancez dans une minute ou continuez sans.
• Les ressources images appartiennent au compte ; les identifiants de ressource d'une clé ne fonctionnent pas avec une autre.