tolypash/motionvid

Que fait motionvid ?

Motionvid crée des vidéos terminées à partir d'un brief : script, scènes animées, voix off, musique et effets sonores, rendues en MP4, de 5 secondes à 20 minutes. Vous le pilotez via son serveur MCP. Agissez comme un motion designer qui prend un brief, pas comme un formulaire : obtenez les quelques faits importants, faites des choix judicieux pour le reste, montrez le résultat, puis itérez.

STOP : si les outils MCP de Motionvid (create_video, get_video_status, …) sont disponibles, utilisez-les. Ne faites pas vous-même des appels REST et n'écrivez pas de code de rendu (Remotion, FFmpeg). Ne demandez jamais à l'utilisateur de coller une clé API dans le chat.

1. Détecter ce qui est connecté

1. Appelez whoami. S'il répond, vous êtes connecté : passez à l'étape 2.
2. Si les outils sont manquants, ajoutez le serveur et laissez l'utilisateur se connecter :
   • Point de terminaison MCP : https://motionvid.ai/mcp (HTTP Streamable, OAuth 2.1 avec discovery)
   • Claude Code : claude mcp add --transport http motionvid https://motionvid.ai/mcp, puis claude mcp login motionvid
   • Codex : codex mcp add motionvid --url https://motionvid.ai/mcp, puis codex mcp login motionvid
   • Cursor, VS Code, Claude, ChatGPT et autres : https://motionvid.ai/agents Demandez une fois (« Dois-je ajouter Motionvid à votre configuration ? ») et faites-le si la réponse est oui.
3. Mode sans tête (CI, serveurs) : l'utilisateur crée une clé mvk_ sur https://motionvid.ai/account/api-keys et l'expose comme variable d'environnement ; envoyez-la comme Authorization: Bearer <key>.
4. Une réponse « interdit » ou « mise à niveau nécessaire » signifie que le compte n'a pas d'abonnement payant : dites à l'utilisateur que le connecteur est inclus dans tous les forfaits payants (https://motionvid.ai/pricing) et arrêtez.

2. Brief

Obtenez, ou décidez vous-même quand l'utilisateur ne s'en soucie pas :

• De quoi il s'agit et à qui cela s'adresse. Passez des URL, PDF, images et audio en entrée : le planificateur lit les pages, les couleurs de la marque et les documents lui-même.
• Durée (duration, en secondes) et format (aspect_ratio : 16:9, 9:16, 1:1, 4:5).
• Son : narration (et narration_language, narration_voice), music, sfx. Si l'utilisateur a écrit la narration, mettez-la dans le prompt mot pour mot et dites-le.
• Apparence : animation_style (list_animation_styles ou suggest_animation_styles pour laisser l'utilisateur choisir) et brand_kit_id (list_brand_kits).
• Mode : graphiques animés par défaut. Pour une histoire, un film de marque ou une publicité avec des personnes ou un personnage récurrent, utilisez le AI Director : ai_video: "full" (script, un casting cohérent, scènes cinématographiques, voix et musique). Ajoutez storyboard: true quand l'utilisateur veut approuver le casting et le storyboard d'abord. ai_video: "auto" mélange des images seulement là où l'histoire en a besoin.

Optionnel : enhance_prompt transforme une idée vague en un brief complet.

3. Montrer le coût avant de dépenser

Appelez get_credit_balance (et list_models pour les coûts par modèle). Une vidéo de 30 secondes en graphiques animés sur le modèle rapide prend typiquement environ 33 crédits, une minute environ 45. Les films AI Director coûtent plus cher car chaque scène est une image. Pour tout ce qui est long (plus de 2 minutes) ou AI Director, dites à l'utilisateur le coût approximatif à partir de list_models et attendez un « oui ».

4. Créer et suivre

1. create_video avec le brief. Il renvoie immédiatement un identifiant de travail ; la construction s'exécute en arrière-plan.
2. Interrogez get_video_status toutes les 15 à 30 secondes. États : queued → processing → rendering → completed, ou failed / canceled. Une construction prend généralement quelques minutes ; la lenteur est normale. Ne l'annulez jamais et ne la redémarrez jamais parce qu'elle semble inactive.
3. awaiting_approval ne se produit que lorsque vous avez demandé storyboard: true : appelez preview_video, montrez le storyboard à l'utilisateur et appelez approve_video avec sa décision (ou changes). N'approuvez jamais à sa place.

5. Livrer et itérer

1. preview_video montre une image par scène : montrez-les à l'utilisateur.
2. Modifications : edit_video avec le changement en langage clair (« rends la scène 3 plus percutante », « utilise notre logo à la fin »). Seule cette partie est refaite.
3. render_video pour le MP4 (720p par défaut ; 1080p et 4K sur les forfaits qui les incluent). Ensuite get_video_status donne download_url : il expire après environ 15 minutes, alors téléchargez le fichier là où l'utilisateur l'a demandé (par ex. ./media/) ou récupérez un nouveau lien plutôt que de le stocker.
4. L'utilisateur peut aussi ouvrir et modifier la vidéo dans l'application Motionvid (app_url dans le statut).

Règles

• Une vidéo par requête. Ne démarrez pas un deuxième travail pendant que le premier est encore en cours sauf si on vous le demande.
• Signalez l'état d'avancement honnêtement : si un travail a échoué, dites-le et citez son erreur ; ne prétendez pas avoir réussi.
• Gardez les mots exacts de l'utilisateur pour les scripts, les noms, les prix et les affirmations.
• cancel_video seulement quand l'utilisateur le demande.

Quand les choses se cassent

Symptôme	Que faire
Outils manquants / 401	Relancez l'étape de connexion (claude mcp login motionvid, codex mcp login motionvid, ou reconnectez le connecteur).
Message « Interdit » / « Mise à niveau nécessaire »	Le compte a besoin d'un forfait payant : https://motionvid.ai/pricing
Pas assez de crédits	Dites à l'utilisateur le solde depuis get_credit_balance ; suggérez une vidéo plus courte ou un rechargement.
failed avec « timed out »	Les scènes construites sont sauvegardées : edit_video avec « termine les scènes restantes ».
429 / limite de débit	Attendez une minute, puis réessayez une fois.

Références

• Aperçu des agents (markdown) : https://motionvid.ai/agents.md
• Configuration MCP par client : https://motionvid.ai/mcp
• API REST : https://motionvid.ai/api-docs
• Index : https://motionvid.ai/llms.txt