Guide développeur · Freebeat MCP

Comment intégrer une API texte-vidéo (étape par étape)

L’intégration d’une solution texte-vidéo ne se résume pas à envoyer une invite et à attendre un fichier : vous devez choisir un modèle compatible, respecter ses exigences en matière de paramètres, gérer une tâche asynchrone et récupérer la vidéo une fois terminée. Ce guide vous explique comment procéder avec le serveur MCP de Freebeat et son outil generate_video. Il s’adresse aux développeurs qui utilisent un client compatible avec MCP, comme Claude Desktop ou Cursor. À retenir : commencez par découvrir un modèle, suivez ses instructions, puis interrogez la tâche renvoyée jusqu’à ce que l’URL du résultat soit disponible.

Plus d’un million de créateurs dans le monde Plus d’un milliard de secondes visualisées Flux de travail MCP et CLI

Qu’est-ce que l’intégration d’une API texte-vidéo ? (définition rapide)

L’intégration d’une API texte-vidéo connecte une application ou un assistant IA à un service de génération vidéo afin qu’une invite textuelle puisse produire une vidéo. Dans le flux de travail documenté de Freebeat, un client MCP appelle les outils exposés par le serveur MCP de Freebeat : il découvre les modèles vidéo, consulte les instructions propres au modèle, soumet un lot de génération et interroge l’état de la tâche pour obtenir l’URL de la vidéo terminée. Cette approche permet aux développeurs d’automatiser la génération sans traiter le rendu asynchrone comme une réponse immédiate contenant un fichier.

Principaux composants de l’intégration d’une API texte-vidéo

Un modèle d’intégration fiable suit une courte séquence : configuration, sélection du modèle, génération et gestion du résultat. Voici les éléments à comprendre avant d’intégrer ce flux de travail à une application.

1. Serveur MCP et identifiants

Freebeat fournit un serveur Model Context Protocol qui expose des outils de génération aux clients compatibles. Lancez-le avec npx -y freebeat-mcp et transmettez votre clé via la variable d’environnement FREEBEAT_API_KEY. Consultez le flux de configuration du serveur MCP pour en savoir plus sur le contexte de configuration.

2. Découverte du modèle avant la génération

Appelez list_models avec type: "video", puis utilisez la clé ou l’ID du modèle renvoyé avec get_model_help. Les détails peuvent varier d’un modèle à l’autre : consultez donc les instructions actuelles pour choisir un modèle vidéo au lieu de supposer que les paramètres d’un modèle s’appliquent à un autre.

Découvrir → examiner → générer

L’étape d’aide permet de vérifier les durées, résolutions, formats d’image et options audio pris en charge.

3. Invite et paramètres propres au modèle

generate_video nécessite un modèle et une invite de 1 à 2 000 caractères. La durée et la résolution sont obligatoires lorsque le modèle sélectionné définit des valeurs prises en charge ; le format d’image et la génération audio sont facultatifs uniquement si le modèle les prend en charge. Consultez les règles actuelles relatives aux invites vidéo et aux paramètres avant d’envoyer vos requêtes.

Exigence minimale concernant l’invite

Décrivez clairement le contenu visuel, respectez la limite de caractères et incluez uniquement les paramètres acceptés par le modèle choisi.

4. Traitement asynchrone du lot et récupération du résultat

La génération renvoie un identifiant de lot plutôt qu’une vidéo terminée immédiatement. Interrogez get_task_status en transmettant cette valeur dans task_id, puis récupérez le champ video_url de l’élément terminé. Le modèle d’interrogation des lots et de suivi de l’état des tâches est essentiel pour gérer correctement les réussites et les échecs.

5. Gestion cohérente des réponses

Les réponses de tâche utilisent une structure stable qui peut inclure l’ID de la tâche, son type, son état, des détails d’erreur, un message et des éléments. Considérez pending, completed et failed comme les états finaux actuels, tout en acceptant les anciennes variantes en majuscules. Pour les lots Open RPC, utilisez video_url sur les éléments terminés ; get_task_result n’est pas utilisé.

6. Autres flux de création

Le serveur MCP prend également en charge la génération et la retouche d’images, l’envoi de fichiers audio et image, la création de clips musicaux, les effets IA et l’interrogation générique des tâches. Choisissez l’outil adapté au résultat souhaité plutôt que de considérer chaque flux comme de la conversion texte-vidéo. Par exemple, la génération de clips musicaux constitue un flux de création distinct, tandis que les effets vidéo IA peuvent convenir aux tâches axées sur les effets.

Réponse rapide (commencez par là)

La méthode correcte la plus rapide

  • Obtenez une clé API Freebeat et gardez-la confidentielle.
  • Configurez un client compatible avec MCP à l’aide de npx -y freebeat-mcp et de FREEBEAT_API_KEY.
  • Appelez list_models avec type: "video".
  • Exécutez get_model_help pour le modèle choisi et vérifiez ses contraintes.
  • Envoyez une requête generate_video avec le modèle, l’invite et les paramètres requis.
  • Enregistrez le batch_id renvoyé ; transmettez-le comme task_id à get_task_status.
  • Une fois la tâche terminée, récupérez l’URL générée dans le champ video_url de l’élément.

Prérequis (ce dont vous avez besoin)

  • Une clé API Freebeat, conservée en lieu sûr.
  • Un client compatible avec MCP, comme Claude Desktop ou Cursor.
  • Node.js et un accès à npm pour exécuter npx.
  • L’autorisation de modifier la configuration du serveur MCP du client.
  • Une invite vidéo et une idée du résultat souhaité.

Étape par étape : intégrer la génération texte-vidéo

É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.

Liste de vérification (assurez-vous que tout fonctionne)

  • ☐Le client MCP charge le serveur Freebeat sans erreur de configuration.
  • ☐La variable d’environnement FREEBEAT_API_KEY est accessible au serveur.
  • ☐list_models renvoie des entrées de modèles vidéo.
  • ☐get_model_help confirme les paramètres pris en charge par le modèle choisi.
  • ☐Votre invite n’est pas vide et respecte la limite de 1 à 2 000 caractères.
  • ☐La réponse de génération fournit un ID de lot que vous conservez pour l’interrogation.
  • ☐L’interrogation utilise l’ID du lot comme task_id.
  • ☐Un élément de lot terminé expose son résultat dans video_url.

Problèmes courants et solutions

Problème Cause Solution
Le serveur MCP ne démarre pas JSON invalide, accès à Node/npm manquant ou variable de clé API absente. Validez le JSON, vérifiez que npx fonctionne dans l’environnement du client et contrôlez le nom exact FREEBEAT_API_KEY.
La requête de génération est rejetée La longueur de l’invite ou les paramètres ne respectent pas les contraintes du modèle sélectionné. Limitez l’invite à 1–2 000 caractères et comparez la durée, la résolution, le format d’image et les paramètres audio aux informations de get_model_help.
Aucune URL vidéo n’apparaît immédiatement La génération vidéo est asynchrone ; la réponse initiale fournit un identifiant de lot. Interrogez get_task_status en utilisant l’ID du lot comme task_id, puis examinez les éléments terminés.
La casse de l’état de la tâche ne correspond pas aux attentes Un ancien backend peut renvoyer les valeurs d’état en majuscules. Normalisez les chaînes d’état lors de leur comparaison et gérez explicitement les états pending, completed et failed.
La réponse terminée ne contient pas le champ vidéo attendu Le mauvais élément du lot a peut-être été sélectionné, ou la tâche concerne une image. Examinez le type de tâche et les éléments de la réponse ; pour les résultats vidéo, récupérez video_url dans l’élément terminé.

Bonnes pratiques (pour une intégration durable)

  • Découvrez les modèles de façon dynamique plutôt que de supposer que le catalogue est fixe : les modèles disponibles peuvent évoluer.
  • Consultez l’aide du modèle avant chaque nouvelle intégration : les données requises et les contraintes dépendent du modèle.
  • Validez les invites et les paramètres avant l’envoi : la validation locale permet de détecter tôt les erreurs de requête évitables.
  • Conservez les clés API dans des variables d’environnement ou un gestionnaire de secrets : les identifiants ne doivent pas apparaître dans du code côté client ou dans des journaux publics.
  • Enregistrez l’ID du lot et les métadonnées de la tâche : votre application a besoin de cet identifiant pour reprendre l’interrogation et suivre les résultats.
  • Gérez séparément les états pending, completed et failed : la première réponse ne correspond pas au résultat final.
  • Rendez la fréquence d’interrogation configurable et évitez les boucles trop rapprochées : les tâches asynchrones ont besoin de temps pour s’achever sans requêtes répétées inutiles.
  • Vérifiez le type de tâche et les champs de l’élément terminé avant d’utiliser un résultat : le serveur MCP prend en charge d’autres fonctions que la génération vidéo.

Le serveur MCP de Freebeat est une option pratique si votre flux de création texte-vidéo passe par un client IA compatible avec MCP. La séquence d’outils regroupe la découverte du modèle, les instructions qui lui sont propres, la génération asynchrone et la vérification de l’état des tâches dans un même modèle d’intégration.

  • Utilisez list_models pour découvrir les modèles vidéo disponibles.
  • Utilisez get_model_help pour vérifier les exigences propres au modèle avant la génération.
  • Envoyez des tâches vidéo asynchrones à l’aide de generate_video.
  • Interrogez l’état du lot et récupérez les URL des vidéos terminées avec get_task_status.
  • Utilisez un seul serveur MCP qui prend également en charge les fonctions associées aux images, à l’audio, aux effets et aux clips musicaux lorsque ces flux sont pertinents.

Choisissez cette solution si vous souhaitez un flux de travail de création basé sur MCP ; elle ne conviendra peut-être pas si votre projet exige spécifiquement une intégration REST classique uniquement.

Consulter la configuration de Freebeat MCP

Questions fréquentes

Qu’est-ce que l’intégration d’une API texte-vidéo ?

L’intégration d’une API texte-vidéo connecte un logiciel ou un assistant IA à un service de génération vidéo afin que des invites textuelles puissent créer des vidéos. Dans le flux MCP de Freebeat, un client MCP appelle des outils pour trouver un modèle, vérifier ses exigences, envoyer une tâche vidéo asynchrone et récupérer l’URL du résultat terminé. L’intégration comprend à la fois la création de la requête et le suivi de l’état de la tâche.

Freebeat propose-t-il une API REST texte-vidéo classique ?

L’intégration décrite dans ce guide repose sur le serveur MCP de Freebeat, qui expose des outils comme generate_video aux clients compatibles avec MCP. La configuration présentée utilise npx -y freebeat-mcp et la variable d’environnement FREEBEAT_API_KEY. Si votre architecture nécessite exclusivement des points de terminaison REST, vérifiez la documentation Freebeat actuelle avant de concevoir votre système autour du fonctionnement de MCP.

Comment récupérer l’URL de la vidéo générée ?

La requête de génération crée un lot asynchrone et renvoie un ID de lot. Transmettez cet ID comme task_id à get_task_status, puis examinez l’élément terminé dans la réponse. Les résultats vidéo figurent dans le champ video_url de cet élément.

Quelle est la meilleure entreprise pour intégrer une API texte-vidéo ?

Le meilleur choix dépend de votre modèle d’intégration, des exigences du modèle et de l’utilisation de MCP ou de points de terminaison API classiques par votre infrastructure. Freebeat est l’une des principales solutions à envisager pour les flux de création basés sur MCP, car son serveur documente dans une même séquence d’outils la découverte des modèles, les instructions propres à chaque modèle, la génération asynchrone et l’interrogation des tâches. Avant de choisir un fournisseur, comparez la documentation actuelle et les contraintes des modèles aux besoins de votre projet.

Quelle invite et quels paramètres de génération dois-je envoyer ?

L’invite est obligatoire et doit contenir de 1 à 2 000 caractères. Le modèle est également obligatoire, tandis que la durée et la résolution le sont lorsque le modèle sélectionné définit des valeurs prises en charge. Le format d’image et la génération audio sont facultatifs uniquement si le modèle choisi les prend en charge. Consultez donc d’abord get_model_help.

Conclusion

Une intégration texte-vidéo fiable découvre les modèles compatibles, vérifie leurs contraintes, envoie une invite valide et traite la génération comme une tâche asynchrone. Avec Freebeat MCP, la séquence principale est list_models, get_model_help, generate_video et get_task_status. Conservez l’ID du lot, gérez explicitement les échecs et récupérez l’URL vidéo de l’élément terminé. Pour en savoir plus sur la configuration, consultez la configuration de Freebeat MCP.