Eén videoworkflow, drie ingangen: Public API, Webhooks en MCP

De eerste CaptionBolt-workflow speelde zich volledig in de browser af. Je uploadde een video, wachtte op het transcript, controleerde de ondertitels en exporteerde het resultaat.

Voor één video is dat nog steeds de duidelijkste manier. Wanneer hetzelfde werk elke dag terugkomt, wordt het minder logisch.

Een cursusteam neemt misschien vijf lessen tegelijk op. Een bureau wil mogelijk klantvideo’s voorbereiden zodra de bronbestanden binnenkomen. Een ontwikkelaar heeft misschien al een intern systeem dat weet welke opname is goedgekeurd, wie deze moet controleren en waar het eindbestand thuishoort. ID’s tussen tabbladen kopiëren is geen creatief werk. Een statuspagina blijven verversen ook niet.

We hoorden steeds een versie van dezelfde vraag: kan CaptionBolt in de workflow passen die we al hebben?

Ons antwoord is nu ja. CaptionBolt heeft een Public API, ondertekende Webhooks en een gehoste remote MCP-server voor compatibele AI-assistenten. Het zijn drie ingangen naar hetzelfde product, geen drie nieuwe videoproducten achter technische namen.

De browser is niet langer de enige ingang

We wilden geen aparte ‘ontwikkelaarsversie’ van CaptionBolt bouwen.

Projecten uit de Public API gebruiken hetzelfde account, dezelfde verwerkingsminuten, abonnementslimieten, ondertitelstijlen, opgeslagen presets en exportrechten als projecten uit de app. Een project kan in een automatisering beginnen, in CaptionBolt pauzeren voor menselijke controle en via de API doorgaan nadat de wijzigingen zijn opgeslagen.

Dat laatste is belangrijk. Automatisering hoort herhaalde coördinatie weg te nemen zonder stilletjes het menselijke oordeel te verwijderen.

De standaardintegratiemodus is review. CaptionBolt bereidt het transcript en de ondertitels voor en laat het project klaarstaan voor een persoon. auto-export is beschikbaar wanneer een workflow die stop echt niet nodig heeft, maar moet bewust worden gekozen.

Public API: voorspelbaar werk voor voorspelbare systemen

De REST API is de directe keuze voor software die je zelf beheert.

Deze kan accountlimieten lezen, ondertitelstijlen en opgeslagen presets vinden, een video in hervatbare delen uploaden, een project maken, de status controleren, een export aanvragen en het eindresultaat ophalen. Opdrachten geven snel een bewerking terug die je kunt volgen, in plaats van één verzoek tijdens de hele videoverwerking open te houden.

Idempotentie maakte ook deel uit van de eerste release. Als een netwerkverzoek verloopt, kan je systeem dezelfde bedoeling met dezelfde idempotentiesleutel herhalen. Je hoeft niet te raden of er een tweede project moet worden gemaakt. Videoverwerking heeft te veel lange stappen om ‘de verbinding werd verbroken’ gelijk te stellen aan ‘er is niets gebeurd’.

De praktische toepassingen zijn niet exotisch. Een formulier kan een project aanmaken. Een contentkalender kan de resulterende project-ID aan een bestaand item koppelen. Een klantportaal kan laten zien of een video wordt verwerkt, klaarstaat voor controle, wordt geëxporteerd of is voltooid. Jouw systeem regelt de coördinatie; CaptionBolt regelt de ondertitelworkflow.

Je blijft verantwoordelijk voor het bewaren van de API Key op de server, het aanvragen van alleen de scopes die de integratie nodig heeft en het opslaan van voltooide bestanden voordat hun toegangsperiode eindigt. De REST API-handleiding doorloopt het volledige traject van upload tot resultaat. De actuele API-referentie bevat de schema’s voor verzoeken en antwoorden.

Webhooks: ga verder wanneer er echt iets verandert

Polling is nuttig wanneer iemand op één scherm wacht. Het is een slechte manier om twee systemen dagen of weken met elkaar te verbinden.

Met Webhooks kan CaptionBolt je HTTPS-endpoint informeren wanneer een project klaarstaat voor controle, voltooid is, mislukt of geannuleerd is. Zo kan een kaart in een interne wachtrij worden verplaatst, de juiste persoon een melding krijgen of de volgende goedgekeurde stap beginnen zonder iedere paar seconden naar de status te vragen.

De events zijn ondertekend. De ontvanger moet de handtekening aan de hand van de ruwe request body controleren, verouderde timestamps weigeren en vóór verwerking op event-ID dedupliceren. Leveringen kunnen worden herhaald of in een andere volgorde aankomen, dus de ontvanger moet ook idempotent zijn. Mislukt een levering, dan probeert CaptionBolt het nog twee keer — na ongeveer één minuut en vijf minuten — voordat de automatische pogingen stoppen. Na het herstellen van de ontvanger kun je recente leveringen bekijken en er één handmatig opnieuw sturen.

Het event bevat projectmetadata, niet de video zelf. Een voltooiingsevent verwijst je systeem naar het beveiligde resultaat-endpoint, waar het een nieuwe downloadlink kan aanvragen. Die scheiding houdt de melding klein en de toegang onder de rechten van de API Key.

De Webhooks-handleiding behandelt eventtypen, handtekeningcontrole, nieuwe pogingen, secretrotatie en het testen van een endpoint voordat je erop vertrouwt.

MCP: laat een AI-assistent tools gebruiken, geen schermen raden

De Public API past goed wanneer een ontwikkelaar de volgorde al heeft bepaald. MCP is nuttig wanneer de volgende stap van een gesprek afhangt.

MCP staat voor Model Context Protocol. Een compatibele AI-assistent kan verbinding maken met het gehoste MCP-endpoint van CaptionBolt en een begrensde set tools ontdekken: projecten tonen, accountlimieten bekijken, stijlen of presets vinden, een uploadsessie beheren, een project maken, de status controleren, een export aanvragen, opnieuw proberen, annuleren en een resultaat ophalen.

Dat betekent niet dat een agent onbeperkte controle krijgt.

Je maakt in Settings → Integrations een aparte API Key aan, kiest de benodigde scopes en bewaart de sleutel in de geheime instellingen van de MCP-host, niet in een prompt. De host moet remote HTTP MCP met een Bearer-header ondersteunen. Verbindingen die alleen OAuth gebruiken, maken geen deel uit van deze release.

De instructie kan vervolgens klinken als een normale werkafspraak:

Toon de CaptionBolt-projecten die klaarstaan voor controle. Laat me de nieuwste drie zien en exporteer niets voordat ik toestemming geef.

De assistent kan bepalen welke tool hierna wordt aangeroepen, maar CaptionBolt handhaaft nog steeds de scopes van de API Key, het huidige abonnement, projecteigendom, credits en geldige statusovergangen. Als de sleutel niet mag exporteren, verandert een zelfverzekerde zin van het model daar niets aan.

Dit is het deel van MCP dat ons het meest interesseert. Een assistent kan met echte projectstatus werken in plaats van op basis van een beschrijving te doen alsof hij een dashboard begrijpt. Het product krijgt ook een harde grens: de assistent kan alleen de tools en rechten gebruiken die wij beschikbaar stellen.

Bekijk de handleiding voor remote MCP voor het endpoint, de verbindingsvereisten en een eerste workflow waarin controle vóór export komt.

Drie ingangen, één set regels

REST, Webhooks en MCP lossen verschillende coördinatieproblemen op:

• REST start werk en leest de status vanuit software die je beheert.
• Webhooks informeren die software wanneer een betekenisvol projectevent plaatsvindt.
• MCP laat een compatibele AI-assistent tijdens een gesprek uit dezelfde begrensde tools kiezen.

Daaronder volgen ze dezelfde regels voor projecten en exports.

Dat was zowel een architectuur- als een productkeuze. Een tweede pipeline alleen voor automatisering zou uiteindelijk van de app afwijken bij ondertitels, credits, projecteigendom, controlestatus of exports. Integraties hergebruiken daarom de workflow die we al maanden robuuster maken.

Dat betekent ook dat integraties de productgrenzen van CaptionBolt niet omzeilen. De API werkt met materiaal dat je al hebt gekozen. Deze zoekt geen virale clips in een lange opname, kadreert niet automatisch iedere spreker opnieuw, dubt geen video, vertaalt geen ondertitels en publiceert niet op sociale platforms. Importeren via een externe URL en losstaande Transcript-aanmaak vallen ook buiten de eerste release.

Die grenzen zijn geen voetnoten. Ze maken bruikbare automatisering mogelijk zonder de verzameling half verwante producten te heropenen die we bewust hebben stopgezet.

Een goede eerste automatisering is saai

De beste eerste test is geen volledig autonome contentmachine. Het is één echte video en één herhaalde overdracht.

Bijvoorbeeld:

1. Maak een aparte API Key met lees- en schrijftoegang voor projecten. Voeg export- of Webhook-rechten alleen toe als de workflow ze nodig heeft.
2. Upload een bekende video en maak het project in review-modus.
3. Abonneer je op het gereed-event in plaats van voortdurend te pollen.
4. Open het project in CaptionBolt, corrigeer het transcript en sla het resultaat op.
5. Vraag de export vanuit je systeem aan, of laat een verbonden assistent de actie voorbereiden en op goedkeuring wachten.
6. Ontvang het voltooiingsevent, haal een nieuwe resultaatlink op en sla het bestand op waar je workflow het verwacht.

Als die route betrouwbaar is, verwijder je de handmatige coördinatie die echt alleen herhaling is. Behoud de controlemomenten die de woorden, kadrering en het eindresultaat beschermen.

Voor wie we dit hebben gebouwd

De integratielaag is voor mensen die al weten waar CaptionBolt in hun proces thuishoort.

Dat kan een ontwikkelaar zijn die ondertitelde video aan een bestaand product toevoegt, een bureau dat klantintake aan een interne controlerij koppelt, een cursusteam dat lessen in batches verwerkt of iemand in operations die een AI-assistent het juiste project wil laten vinden zonder door tabbladen te zoeken.

De integratie is geen vereiste voor CaptionBolt. Als je één video tegelijk afwerkt, blijft de browser de eenvoudigste route. De API moet een korte workflow niet in een engineeringproject veranderen alleen omdat er een endpoint bestaat.

Public API, remote MCP en Webhooks zijn beschikbaar voor Max-abonnees. Begin bij Settings → Integrations, lees het integratieoverzicht en houd de API-referentie bij de hand tijdens het bouwen.

Begin met één overdracht. Maak die betrouwbaar. Automatiseer daarna de volgende.