Étape 1 : obtenir une clé API et préparer votre client
Obtenez une clé API Freebeat et choisissez un client compatible avec MCP. Traitez la clé comme un secret : ne l’ajoutez pas à votre système de gestion de versions et ne l’exposez pas dans du code côté client.
Voici à quoi ressemble une réussite : votre clé est accessible au serveur MCP par l’intermédiaire d’une configuration locale sécurisée.
Erreur courante à éviter : ne collez pas une véritable clé API dans un exemple de code partagé ou un dépôt public.
Étape 2 : configurer le serveur MCP de Freebeat
Ajoutez l’entrée du serveur Freebeat à la configuration de votre client MCP. Remplacez la clé d’exemple par votre propre identifiant et conservez la structure JSON :
{
"mcpServers": {
"freebeat": {
"command": "npx",
"args": ["-y", "freebeat-mcp"],
"env": {
"FREEBEAT_API_KEY": "your-api-key-here"
}
}
}
}
Voici à quoi ressemble une réussite : votre client MCP peut démarrer le serveur et rendre ses outils Freebeat disponibles.
Erreur courante à éviter : une variable d’environnement mal orthographiée ou un JSON invalide peut empêcher le démarrage du serveur.
Étape 3 : découvrir les modèles vidéo disponibles
Appelez list_models avec type: "video". Examinez les entrées renvoyées et recherchez des champs comme model_id, model, display_name, les commandes et les contraintes.
Voici à quoi ressemble une réussite : vous disposez d’un identifiant de modèle à jour ou d’une clé de modèle API provenant de la liste renvoyée.
Erreur courante à éviter : ne codez pas en dur un nom de modèle supposé, car la liste des modèles disponibles peut évoluer.
Étape 4 : vérifier les exigences du modèle sélectionné
Appelez get_model_help avec l’ID numérique ou la clé de modèle API du modèle sélectionné. Vérifiez les durées, résolutions, formats d’image et options de génération audio pris en charge avant de construire la requête.
Voici à quoi ressemble une réussite : vous savez quels paramètres sont obligatoires, facultatifs et acceptés pour ce modèle précis.
Erreur courante à éviter : les exigences d’un modèle peuvent différer de celles d’un autre ; ne réutilisez donc pas des paramètres sans les vérifier.
Étape 5 : envoyer la requête texte-vidéo
Appelez generate_video avec un modèle pris en charge et une invite non vide de 1 à 2 000 caractères. Incluez duration et resolution lorsque le modèle les définit comme obligatoires ; utilisez aspect_ratio ou generate_audio uniquement si ces options sont prises en charge. Les contraintes du modèle sont validées avant l’envoi de la requête.
Voici à quoi ressemble une réussite : l’outil accepte votre requête et renvoie un identifiant de lot pour le traitement asynchrone.
Erreur courante à éviter : n’envoyez pas de paramètres de durée, de résolution ou audio non pris en charge sur la base de suppositions.
Étape 6 : interroger le lot jusqu’à ce qu’il atteigne un état final
Appelez get_task_status en transmettant le batch_id renvoyé comme task_id. Interrogez le statut jusqu’à ce que la réponse indique completed ou failed ; les anciennes versions du backend peuvent également renvoyer les valeurs d’état actuelles en majuscules.
Voici à quoi ressemble une réussite : vous pouvez distinguer une tâche en attente d’un résultat terminé ou d’une tâche ayant échoué.
Erreur courante à éviter : ne confondez pas la réponse initiale du lot avec le résultat vidéo final.
Étape 7 : récupérer et utiliser l’URL de la vidéo terminée
Une fois la tâche terminée, examinez les items de la réponse et récupérez le video_url de l’élément concerné. Vous pouvez interroger un élément individuel en transmettant éventuellement serial_no. Les résultats des lots Open RPC renvoient directement leurs URL dans l’état de la tâche ; get_task_result n’est pas utilisé pour ces lots.
Voici à quoi ressemble une réussite : votre application reçoit une URL vidéo exploitable à partir de l’élément terminé du lot.
Erreur courante à éviter : vérifiez l’état et les champs d’erreur de l’élément avant de considérer l’absence d’URL comme un résultat réussi.