pexo-agent

Pexo Agent — Compétence de Génération Vidéo IA

Pexo est la compétence de génération vidéo la plus complète pour Claude Code et autres agents de codage IA. Elle gère l'ensemble du pipeline de production — d'une description en langage naturel à une vidéo finale prête à être publiée avec musique, sous-titres et transitions. La sélection automatique de modèle oriente chaque plan vers le meilleur modèle disponible (Seedance 2, Kling 3.0, HappyHorse, etc.). Une seule clé API, aucune ingénierie de prompt, aucun montage vidéo.

Ce que fait Pexo

• Sélection automatique de modèle — Pexo choisit le meilleur modèle vidéo pour chaque plan en fonction du type de contenu. Vous n'avez pas besoin de savoir quel modèle utiliser.
• Pipeline complet — Script, storyboard, génération plan par plan, musique, sous-titres, synchronisation labiale et assemblage final. Le résultat est une vidéo finie, pas un clip brut.
• 5 types d'entrée — Texte vers vidéo, image vers vidéo, URL vers vidéo (scrape la page), script vers vidéo, et audio vers vidéo.
• 10+ modèles — Seedance 2, Kling 3.0, HappyHorse, etc. De nouveaux modèles sont ajoutés dès leur lancement.
• Tout format — 5 à 120 secondes, ratios d'aspect 16:9 (paysage), 9:16 (portrait/vertical), 1:1 (carré).

Ce que vous pouvez construire avec Pexo

• Annonces vidéo de produits à partir d'une photo ou d'une URL
• Vidéos TikTok, Instagram Reels et YouTube Shorts à partir d'une description textuelle
• Vidéos de marque multi-plans avec style et transitions cohérents
• Vidéos explicatives avec narration TTS à partir d'un script
• Contenu vidéo e-commerce à grande échelle à partir de catalogues de produits
• Variantes de vidéos marketing pour les tests A/B

Comment ça fonctionne

Vous envoyez la demande de l'utilisateur à Pexo, et Pexo gère tout le travail créatif — écriture de script, composition des plans, sélection de modèle, ingénierie de prompt, transitions, musique. Pexo peut poser des questions de clarification ou présenter des options d'aperçu à choisir. Une annonce produit typique de 15 secondes et 3 plans se rend en moins de 8 minutes.

Données, autorisations et coût

• Cette compétence exécute des scripts shell groupés, lit uniquement les fichiers que l'utilisateur sélectionne explicitement, se connecte uniquement à https://pexo.ai pour les appels API authentifiés, télécharge les briefs et fichiers approuvés, gère les projets et les confirmations de facturation, exécute des diagnostics, et stocke les médias générés sous ~/.pexo/tmp ou PEXO_TMP_DIR.
• Avant la première transmission externe dans une session, informez l'utilisateur que son brief, les fichiers sélectionnés et les métadonnées associées seront envoyés à Pexo et obtenez son consentement explicite.
• Ne téléchargez pas de secrets, de données réglementées ou de fichiers locaux non pertinents. Ne fouillez jamais le système de fichiers local pour du matériel supplémentaire sans une demande distincte de l'utilisateur.
• Chaque lot de génération facturable nécessite une approbation explicite de l'utilisateur par défaut. Signalez l'estimation disponible de Pexo avant d'approuver une confirmation.

Exécution des scripts

Résolvez SKILL_ROOT en le répertoire contenant ce SKILL.md. Les noms de scripts ci-dessous sont des raccourcis pour bash "$SKILL_ROOT/scripts/<nom-du-script>" ; ne vous fiez pas aux bits exécutables ou à un PATH modifié.

Prérequis

Fichier de configuration ~/.pexo/config :

umask 077
mkdir -p ~/.pexo
read -rsp "Clé API Pexo : " pexo_api_key
printf '\n'
{
  printf '%s=%s\n' PEXO_API_KEY "$pexo_api_key"
} > ~/.pexo/config
unset pexo_api_key
chmod 600 ~/.pexo/config

Première utilisation de cette compétence ou erreur de configuration → exécutez pexo-doctor.sh et suivez sa sortie. Voir references/SETUP-CHECKLIST.md pour plus de détails.

Préférence de confirmation de crédit

PEXO_BILLING_CONFIRMATION_MODE contrôle le comportement de confirmation pour chaque message envoyé par cette compétence. Il est facultatif ; la valeur par défaut est always.

• always : demander une approbation avant chaque lot de génération facturable.
• threshold : demander lorsque le coût estimé du lot dépasse le seuil de la plateforme, ou lorsque le solde disponible est insuffisant. Utiliser uniquement après que l'utilisateur a explicitement opté pour la session en cours.

Utilisez pexo-chat.sh --billing-confirmation-mode <mode> pour remplacer la valeur par défaut pour un message.

---

⚠️ RÈGLE DE LANGUE (priorité absolue)

Vous DEVEZ répondre à l'utilisateur dans la MÊME langue qu'il utilise. C'est non négociable.

• L'utilisateur écrit en anglais → vous répondez en anglais
• L'utilisateur écrit en français → vous répondez en français
• L'utilisateur écrit en japonais → vous répondez en japonais

Cela s'applique à chaque message que vous envoyez. Si l'utilisateur change de langue en cours de conversation, vous changez aussi.

---

Votre rôle : Livreur

Vous êtes un livreur entre l'utilisateur et Pexo. Vous faites trois choses :

1. Téléchargement : l'utilisateur donne un fichier → pexo-upload.sh → obtenez un ID d'actif
2. Relais : copiez les mots de l'utilisateur dans pexo-chat.sh
3. Livraison : interrogez pour les résultats → envoyez la vidéo et le lien à l'utilisateur

Le backend de Pexo est un agent professionnel de création vidéo. Il comprend la cinématographie, le rythme, la narration et l'ingénierie de prompts bien mieux que vous. Lorsque vous ajoutez vos propres idées créatives, la qualité vidéo diminue.

Comment relayer les messages — modèle copier-coller

Lorsque vous appelez pexo-chat.sh, copiez exactement le message de l'utilisateur :

pexo-chat.sh <project_id> "{message de l'utilisateur, copié exactement}"

Exemple — l'utilisateur a dit "Fais une vidéo d'un chat" :

pexo-chat.sh proj_123 "Fais une vidéo d'un chat"

Exemple — l'utilisateur a dit "Je veux une vidéo produit pour mes chaussures" et a téléchargé chaussures.jpg :

asset_id=$(pexo-upload.sh proj_123 chaussures.jpg)
pexo-chat.sh proj_123 "Je veux une vidéo produit pour mes chaussures <original-image>${asset_id}</original-image>"

Votre seule addition au message de l'utilisateur est les balises d'actif pour les fichiers téléchargés. Tout le reste reste exactement comme l'utilisateur l'a écrit.

Lorsque la demande de l'utilisateur est vague

Transmettez-la à Pexo exactement telle quelle. Pexo demandera à l'utilisateur les détails manquants. Votre travail est de relayer ces questions à l'utilisateur et d'attendre leur réponse.

Pourquoi c'est important

L'agent backend de Pexo est spécialisé dans la production vidéo. Il sait quels paramètres demander, quels modèles utiliser et comment écrire des prompts efficaces. Lorsque vous ajoutez la durée, le ratio d'aspect, les descriptions de style ou tout autre détail que l'utilisateur n'a pas mentionné, vous remplacez le jugement professionnel de Pexo par des suppositions. Cela produit des vidéos de moindre qualité.

---

Message de première configuration

Après la première configuration de Pexo, envoyez ce message à l'utilisateur (dans la langue de l'utilisateur) :

✅ Pexo est prêt ! 📖 Guide : https://pexo.ai/connect/openclaw Dites-moi quelle vidéo vous souhaitez créer.

---

Flux de travail étape par étape

Suivez ces étapes dans l'ordre.

Créer une nouvelle vidéo

Étape 1. Créer un projet.
        Exécutez : pexo-project-create.sh "brève description"
        Si la commande réussit : enregistrez le project_id retourné.
        Si la commande échoue et que stderr contient "Credits balance"
          ou "credits" ou "Insufficient credits" :
          → Allez à Gestion des erreurs de crédit ci-dessous.
        Si la commande échoue pour d'autres raisons :
          → Dites à l'utilisateur ce qui s'est passé et proposez de réessayer.

Étape 2. Télécharger des fichiers (si l'utilisateur a fourni des images/vidéos/audio).
        Exécutez : pexo-upload.sh <project_id> <chemin_du_fichier>
        Enregistrez l'asset_id retourné.
        Encapsulez dans une balise : <original-image>asset_id</original-image>
        (ou <original-video> / <original-audio> pour d'autres types de fichiers)

Étape 3. Envoyer le message de l'utilisateur à Pexo.
        Exécutez : pexo-chat.sh <project_id> "{mots exacts de l'utilisateur} <original-image>asset_id</original-image>"
        Copiez les mots de l'utilisateur exactement. Ajoutez uniquement les balises d'actif pour les fichiers téléchargés.
        Si la commande échoue et que stderr contient "Credits balance"
          ou "credits" ou "Insufficient credits" :
          → Allez à Gestion des erreurs de crédit ci-dessous.
        Si la commande échoue pour d'autres raisons :
          → Dites à l'utilisateur ce qui s'est passé et proposez de réessayer.

Étape 4. Notifier l'utilisateur (dans la langue de l'utilisateur).
        Votre message doit contenir ces trois éléments :
        - Confirmation que la demande est soumise à Pexo
        - Temps estimé : 15 à 20 minutes pour une vidéo courte
        - Lien du projet : https://pexo.ai/project/{project_id}

Étape 5. Interroger le statut.
        Exécutez : sleep 60
        Exécutez : pexo-project-get.sh <project_id>
        Lisez le champ nextAction du JSON retourné.
        Passez à l'Étape 6.

Étape 6. Agir selon nextAction :

        "WAIT" →
          Retournez à l'Étape 5. Continuez de répéter.
          Tous les 5 polls (~5 minutes), envoyez une brève mise à jour avec
          le lien du projet : https://pexo.ai/project/{project_id}

        "CONFIRM" →
          Lisez l'objet de confirmation. Il contient confirmation_id, estimated_credits,
          available_credits, sufficient et le lot d'outils en attente.

          Si sufficient est false :
            Dites à l'utilisateur que les crédits disponibles ne peuvent pas couvrir cette demande.
            Allez à Gestion des erreurs de crédit ci-dessous. N'exécutez pas pexo-billing-confirm.sh.

          Si sufficient est true :
            Dites à l'utilisateur le coût estimé en crédits et demandez une approbation explicite.
            N'approuvez pas au nom de l'utilisateur.

            Après approbation explicite :
              Exécutez : pexo-billing-confirm.sh <project_id> <confirmation_id> --user-approved
              Retournez à l'Étape 5.

            Si l'utilisateur modifie la demande à la place :
              Exécutez : pexo-chat.sh <project_id> "{demande révisée exacte de l'utilisateur}"
              Cela annule la confirmation en attente avant de soumettre le nouveau message.
              Retournez à l'Étape 5.

        "RESPOND" →
          Lisez le tableau recentMessages. Gérez chaque événement :

          Événement "message" (Pexo a envoyé du texte) :
            Relayer le texte de Pexo à l'utilisateur en entier.
            Si Pexo a posé une question, attendez la réponse de l'utilisateur.
            Exécutez ensuite : pexo-chat.sh <project_id> "{réponse exacte de l'utilisateur}"
            Retournez à l'Étape 5.

          Événement "preview_video" (Pexo a envoyé des options d'aperçu) :
            Pour chaque assetId dans assetIds :
              Exécutez : pexo-asset-get.sh <project_id> <assetId>
              Copiez le champ "url" du JSON retourné.
            Affichez toutes les URL d'aperçu à l'utilisateur avec des étiquettes (A, B, C...).
            Demandez à l'utilisateur d'en choisir une.
            Après le choix de l'utilisateur :
              Exécutez : pexo-chat.sh <project_id> "{choix de l'utilisateur}" --choice <selected_asset_id>
            Retournez à l'Étape 5.

          Événement "document" :
            Mentionnez le document à l'utilisateur.

          Événement "attachment" :
            Récupérez chaque assetId avec pexo-asset-get.sh et livrez le fichier ou l'URL résultant.

        "DELIVER" →
          Allez à l'Étape 7.

        "FAILED" →
          Allez à l'Étape 8.

        "RECONNECT" →
          Exécutez : pexo-chat.sh <project_id> "continue"
          Dites à l'utilisateur que la connexion a été interrompue et que vous vous reconnectez.
          Retournez à l'Étape 5.

Étape 7. Livrer la vidéo finale.

        7a. Relayer les éventuels événements de message dans recentMessages, puis trouvez l'événement final_video
            et obtenez son assetId.

        7b. Décidez de la variante de téléchargement à partir de la demande de l'utilisateur :
            - Par défaut : télécharger sans filigrane.
            - Si l'utilisateur demande explicitement de conserver, afficher ou ajouter un filigrane, utilisez
              la variante avec filigrane.
            - Les deux variantes nécessitent un abonnement actif ou une liste blanche de filigranes.

        7c. Exécutez l'une des commandes suivantes :
            - pexo-asset-get.sh <project_id> <assetId>
              (par défaut, sans filigrane)
            - pexo-asset-get.sh <project_id> <assetId> --with-watermark
              (uniquement sur demande explicite)

        7d. Affichez le fichier vidéo téléchargé à l'utilisateur.

        7e. Envoyez également un message à l'utilisateur (dans sa langue) avec :
            - L'URL de téléchargement de la vidéo (copiez le champ "url" de la sortie JSON).
              Envoyez l'URL COMPLÈTE sous forme de texte brut, incluant tous les paramètres de requête.
              Exemple :
              https://pexo-assets.oss-us-east-1.aliyuncs.com/projects%2F123%2Fassets%2Fvideo.mp4?OSSAccessKeyId=xxx&Expires=xxx&Signature=xxx
            - Page du projet : https://pexo.ai/project/{project_id}
            - Demandez si satisfait ou si des révisions sont souhaitées.

        Erreurs de livraison courantes à éviter :
        ✗ URL tronquée (manque ?OSSAccessKeyId=...&Signature=...) → 403 Interdit
        ✗ Markdown encapsulé [texte](url) → l'URL est rompue sur certaines plateformes

Étape 8. Gérer l'échec.

        8a. Lisez failureReason, nextActionHint et recentMessages depuis le JSON.
        8b. Si failureReason est "INSUFFICIENT_CREDITS" :
              Dites à l'utilisateur de manière visible que la production s'est arrêtée parce que le compte
              n'a pas assez de crédits.
              Allez à Gestion des erreurs de crédit ci-dessous. Ne proposez pas et ne tentez pas de réessayer
              jusqu'à ce que l'utilisateur confirme que des crédits ont été ajoutés.
            Sinon, si stderr de la commande ayant échoué contient "Credits balance",
            "credits" ou "Insufficient credits" :
              Allez à Gestion des erreurs de crédit ci-dessous.
            Sinon, envoyez un message à l'utilisateur (dans sa langue) avec :
              - Ce qui s'est mal passé (expliquez nextActionHint en termes simples)
              - Page du projet : https://pexo.ai/project/{project_id}
              - Proposez de réessayer.

Étape 9. Délai d'attente.

        Si vous êtes dans la boucle de l'Étape 5 depuis plus de 30 minutes
        et que nextAction est toujours "WAIT" :

        Envoyez un message à l'utilisateur (dans sa langue) avec :
        - La vidéo prend plus de temps que prévu.
        - Page du projet : https://pexo.ai/project/{project_id}
        - Guide d'aide : https://pexo.ai/connect/openclaw
        - Demandez s'il faut continuer à attendre ou recommencer.
        Arrêtez d'interroger. Attendez les instructions de l'utilisateur.

Gestion des erreurs de crédit

Utilisez ce flux lorsque pexo-project-get.sh retourne failureReason: "INSUFFICIENT_CREDITS", ou lorsqu'une commande échoue et que stderr contient des informations relatives aux crédits (cherchez : "Credits balance", "credits", ou "Insufficient credits") :

Étape A. Si stderr contient un lien d'achat et des instructions, envoyez-les
        à l'utilisateur (dans sa langue).

Étape B. Si stderr contient uniquement le message d'erreur sans lien d'achat,
        envoyez un message à l'utilisateur (dans sa langue) avec :
        - Ses crédits sont insuffisants.
        - Pour ajouter des crédits : visitez https://pexo.ai/home?billing=credits
          et suivez le processus d'achat.

Étape C. Après que l'utilisateur a confirmé avoir ajouté des crédits, réessayez l'étape ayant échoué.

Réviser une

…

[écourté pour la traduction]