Un workflow vidéo, trois portes d’entrée : API publique, Webhooks et MCP

Le premier workflow CaptionBolt se déroulait entièrement dans le navigateur. Vous importiez une vidéo, attendiez la transcription, vérifiiez les sous-titres, puis exportiez le résultat.

C’est toujours la façon la plus claire de terminer une vidéo. Elle l’est moins lorsque le même travail revient chaque jour.

Une équipe de formation peut enregistrer cinq leçons d’un coup. Une agence peut devoir préparer les vidéos d’un client dès l’arrivée des fichiers source. Un développeur dispose peut-être déjà d’un système interne qui sait quel enregistrement est approuvé, qui doit le vérifier et où ranger le fichier final. Copier des identifiants entre des onglets n’est pas un travail créatif. Actualiser une page de statut non plus.

Nous entendions sans cesse différentes versions de la même question : CaptionBolt peut-il s’intégrer au workflow que nous utilisons déjà ?

La réponse est désormais oui. CaptionBolt propose une API publique, des Webhooks signés et un serveur MCP distant hébergé pour les assistants AI compatibles. Ce sont trois façons d’entrer dans le même produit, pas trois nouveaux produits vidéo cachés derrière des termes techniques.

Le navigateur n’est plus la seule porte d’entrée

Nous ne voulions pas créer une « version développeur » séparée de CaptionBolt.

Les projets créés via l’API publique utilisent le même compte, les mêmes minutes de traitement, limites de forfait, styles de sous-titres, presets enregistrés et droits d’exportation que les projets créés dans l’application. Un projet peut commencer dans une automatisation, s’arrêter pour être vérifié dans CaptionBolt, puis reprendre via l’API une fois les modifications enregistrées.

Ce dernier point compte. L’automatisation doit supprimer la coordination répétitive sans faire disparaître discrètement le jugement humain.

Le mode d’intégration par défaut est review. CaptionBolt prépare la transcription et les sous-titres, puis laisse le projet prêt pour une personne. auto-export est disponible lorsqu’un workflow n’a réellement pas besoin de cette pause, mais ce choix doit être explicite.

API publique : un travail prévisible pour des systèmes prévisibles

L’API REST est l’option directe pour les logiciels que vous contrôlez.

Elle permet de consulter les limites du compte, de trouver les styles de sous-titres et vos presets enregistrés, d’importer une vidéo en plusieurs parties avec reprise, de créer un projet, de vérifier son statut, de demander un export et de récupérer le résultat final. Les commandes renvoient rapidement une opération à suivre au lieu de garder une requête ouverte pendant tout le traitement vidéo.

Nous avons également intégré l’idempotence dès la première version. Si une requête réseau expire, votre système peut répéter la même intention avec la même clé d’idempotence, sans devoir deviner s’il faut créer un second projet. Le traitement vidéo comporte trop d’étapes longues pour que « la connexion s’est fermée » signifie « rien ne s’est passé ».

Les cas d’usage concrets n’ont rien d’exotique. L’envoi d’un formulaire peut créer un projet. Un calendrier éditorial peut rattacher l’identifiant obtenu à une entrée existante. Un portail client peut indiquer si une vidéo est en cours de traitement, prête à être vérifiée, en cours d’exportation ou terminée. Votre système coordonne ; CaptionBolt gère le workflow de sous-titrage.

Il vous revient toujours de conserver l’API Key côté serveur, de ne demander que les scopes nécessaires à l’intégration et d’enregistrer les fichiers terminés avant la fin de leur fenêtre d’accès. Le guide de l’API REST détaille tout le parcours, de l’import au résultat, et la référence API en ligne contient les schémas des requêtes et des réponses.

Webhooks : continuer quand quelque chose change vraiment

Interroger le statut en boucle peut être utile lorsqu’une personne attend devant un écran. C’est une mauvaise manière de relier deux systèmes pendant des jours ou des semaines.

Les Webhooks permettent à CaptionBolt de prévenir votre endpoint HTTPS lorsqu’un projet est prêt à être vérifié, terminé, en échec ou annulé. Vous pouvez alors déplacer une carte dans une file interne, prévenir la bonne personne ou lancer l’étape suivante déjà approuvée sans demander le statut toutes les quelques secondes.

Les événements sont signés. Votre récepteur doit vérifier la signature à partir du corps brut de la requête, refuser les timestamps trop anciens et dédupliquer les événements par identifiant avant d’agir. Les livraisons peuvent se répéter ou arriver dans le désordre : le récepteur doit donc rester idempotent. En cas d’échec, CaptionBolt effectue deux nouvelles tentatives — après environ une minute, puis cinq minutes — avant d’arrêter les essais automatiques. Vous pouvez consulter les livraisons récentes et en relancer une manuellement après avoir corrigé le récepteur.

L’événement contient les métadonnées du projet, pas la vidéo elle-même. Un événement de fin renvoie votre système vers l’endpoint de résultat authentifié, où il peut demander un nouveau lien de téléchargement. Cette séparation garde la notification légère et maintient l’accès sous le contrôle des droits de l’API Key.

Le guide des Webhooks présente les types d’événements, la vérification des signatures, les nouvelles tentatives, la rotation des secrets et le test d’un endpoint avant de s’y fier.

MCP : laisser un assistant AI utiliser des outils, pas deviner des écrans

L’API publique convient naturellement lorsqu’un développeur a déjà défini la séquence. MCP est utile lorsque l’étape suivante dépend d’une conversation.

MCP signifie Model Context Protocol. Un assistant AI compatible peut se connecter à l’endpoint MCP hébergé de CaptionBolt et découvrir un ensemble d’outils bien délimité : lister les projets, consulter les limites du compte, trouver des styles ou des presets, gérer une session d’import, créer un projet, vérifier son statut, demander un export, réessayer, annuler et récupérer un résultat.

Cela ne signifie pas donner un contrôle illimité à un agent.

Vous créez une API Key dédiée dans Settings → Integrations, choisissez les scopes dont elle a besoin et conservez la clé dans les paramètres secrets de l’hôte MCP, pas dans un prompt. L’hôte doit prendre en charge MCP distant sur HTTP avec un en-tête Bearer. Les connexions uniquement OAuth ne font pas partie de cette version.

L’instruction peut alors ressembler à un accord de travail ordinaire :

Liste les projets CaptionBolt prêts à être vérifiés. Montre-moi les trois plus récents et n’exporte rien avant mon accord.

L’assistant peut choisir l’outil à appeler ensuite, mais CaptionBolt continue d’appliquer les scopes de l’API Key, le forfait actuel, la propriété du projet, les crédits et les transitions d’état autorisées. Si la clé ne permet pas d’exporter, une phrase assurée du modèle n’y change rien.

C’est la partie de MCP qui nous intéresse le plus. Un assistant peut travailler avec l’état réel du projet au lieu de prétendre comprendre un dashboard à partir d’une description. Le produit conserve aussi une limite ferme : l’assistant ne peut utiliser que les outils et les droits que nous exposons.

Consultez le guide de configuration MCP distant pour retrouver l’endpoint, les conditions de connexion et un premier workflow avec vérification avant export.

Trois entrées, un seul ensemble de règles

REST, Webhooks et MCP répondent à des problèmes de coordination différents :

• REST lance le travail et lit son état depuis un logiciel que vous contrôlez.
• Webhooks préviennent ce logiciel lorsqu’un événement important survient dans le projet.
• MCP permet à un assistant AI compatible de choisir parmi les mêmes outils délimités pendant une conversation.

Sous la surface, tous suivent les mêmes règles de projet et d’exportation.

C’était un choix d’architecture et un choix produit. Un second pipeline réservé à l’automatisation finirait par diverger de l’application sur les sous-titres, les crédits, la propriété du projet, l’état de vérification ou les exports. Les intégrations réutilisent donc le workflow que nous avons déjà passé des mois à rendre plus solide.

Cela signifie aussi que les intégrations ne contournent pas les limites de CaptionBolt. L’API travaille avec des images que vous avez déjà sélectionnées. Elle ne cherche pas des clips viraux dans un long enregistrement, ne recadre pas automatiquement chaque personne, ne double pas une vidéo, ne traduit pas les sous-titres et ne publie pas sur les réseaux sociaux. L’import d’URL distantes et la création indépendante de Transcripts ne font pas non plus partie de la première version.

Ces limites ne sont pas des notes de bas de page. Elles nous permettent de proposer une automatisation utile sans rouvrir la collection de produits peu liés que nous avons volontairement retirés.

Une bonne première automatisation est banale

Le meilleur premier test n’est pas une machine à contenu entièrement autonome. C’est une vraie vidéo et un passage de relais qui se répète.

Par exemple :

1. Créez une API Key dédiée avec un accès en lecture et en écriture aux projets. N’ajoutez les droits d’exportation ou de Webhook que si le workflow en a besoin.
2. Importez une vidéo connue et créez le projet en mode review.
3. Abonnez-vous à l’événement indiquant que le projet est prêt au lieu d’interroger le statut en continu.
4. Ouvrez le projet dans CaptionBolt, corrigez la transcription et enregistrez le résultat.
5. Demandez l’export depuis votre système, ou demandez à un assistant connecté de préparer l’action et d’attendre votre accord.
6. Recevez l’événement de fin, récupérez un nouveau lien vers le résultat et enregistrez le fichier à l’endroit attendu par votre workflow.

Une fois ce parcours fiable, retirez la coordination manuelle qui est vraiment répétitive. Gardez les décisions de vérification qui protègent les mots, le cadrage et le résultat final.

Pour qui avons-nous construit cette couche ?

La couche d’intégration s’adresse aux personnes qui savent déjà où CaptionBolt s’insère dans leur processus.

Il peut s’agir d’un développeur qui ajoute des vidéos sous-titrées à un produit existant, d’une agence qui relie l’arrivée des clients à une file de vérification interne, d’une équipe de formation qui traite des leçons par lots ou d’une personne chargée des opérations qui veut qu’un assistant AI trouve le bon projet sans fouiller dans les onglets.

Elle n’est pas nécessaire pour utiliser CaptionBolt. Si vous terminez une vidéo à la fois, le navigateur reste la solution la plus simple. L’API ne doit pas transformer un workflow court en projet d’ingénierie simplement parce qu’un endpoint existe.

L’API publique, MCP distant et les Webhooks sont disponibles pour les abonnés Max. Commencez dans Settings → Integrations, consultez la présentation des intégrations et gardez la référence API à portée de main pendant le développement.

Commencez par un passage de relais. Rendez-le fiable. Automatisez ensuite le suivant.