Un solo flusso video, tre accessi: API pubblica, Webhook e MCP

Il primo flusso di CaptionBolt viveva interamente nel browser. Caricavi un video, aspettavi la trascrizione, controllavi i sottotitoli ed esportavi il risultato.

È ancora il modo più chiaro per completare un video. Lo diventa meno quando lo stesso lavoro si ripete ogni giorno.

Un team che produce corsi può registrare cinque lezioni insieme. Un’agenzia può dover preparare i video di un cliente appena arrivano i file originali. Uno sviluppatore potrebbe già avere un sistema interno che sa quale registrazione è approvata, chi deve controllarla e dove va salvato il file finale. Copiare ID tra schede non è lavoro creativo. Nemmeno aggiornare di continuo una pagina di stato.

Continuavamo a sentire versioni della stessa domanda: CaptionBolt può entrare nel flusso che usiamo già?

Ora la risposta è sì. CaptionBolt offre un’API pubblica, Webhook firmati e un server MCP remoto in hosting per gli assistenti AI compatibili. Sono tre modi per entrare nello stesso prodotto, non tre nuovi prodotti video nascosti dietro nomi tecnici.

Il browser non è più l’unica porta d’ingresso

Non volevamo costruire una “versione per sviluppatori” separata di CaptionBolt.

I progetti creati tramite l’API pubblica usano lo stesso account, gli stessi minuti di elaborazione, limiti del piano, stili di sottotitoli, preset salvati e permessi di esportazione dei progetti creati nell’app. Un progetto può partire da un’automazione, fermarsi per essere controllato da una persona in CaptionBolt e continuare tramite API dopo il salvataggio delle modifiche.

Quest’ultimo punto conta. L’automazione deve eliminare il coordinamento ripetitivo senza eliminare di nascosto il giudizio umano.

La modalità di integrazione predefinita è review. CaptionBolt prepara la trascrizione e i sottotitoli, poi lascia il progetto pronto per una persona. auto-export è disponibile quando un flusso non ha davvero bisogno di quella pausa, ma va scelto esplicitamente.

API pubblica: lavoro prevedibile per sistemi prevedibili

L’API REST è la scelta diretta per il software che controlli.

Può leggere i limiti dell’account, trovare gli stili di sottotitoli e i preset salvati, caricare un video in parti ripristinabili, creare un progetto, verificarne lo stato, richiedere un’esportazione e recuperare il risultato finale. I comandi restituiscono rapidamente un’operazione da seguire, invece di tenere aperta una richiesta durante l’intera elaborazione del video.

Abbiamo incluso l’idempotenza fin dalla prima versione. Se una richiesta di rete scade, il sistema può ripetere la stessa intenzione con la stessa chiave di idempotenza, senza dover indovinare se creare un secondo progetto. L’elaborazione video comprende troppi passaggi lunghi perché “la connessione si è chiusa” possa significare “non è successo nulla”.

I casi d’uso concreti non sono esotici. L’invio di un modulo può creare un progetto. Un calendario editoriale può associare l’ID risultante a una voce esistente. Un portale clienti può mostrare se un video è in elaborazione, pronto per il controllo, in esportazione o completato. Il tuo sistema coordina; CaptionBolt gestisce il flusso dei sottotitoli.

Resta tua responsabilità conservare l’API Key sul server, richiedere solo gli scope necessari all’integrazione e salvare i file finiti prima della chiusura della finestra di accesso. La guida all’API REST illustra l’intera sequenza, dal caricamento al risultato, mentre la documentazione API aggiornata contiene gli schemi di richieste e risposte.

Webhook: continua quando cambia davvero qualcosa

Controllare ripetutamente lo stato è utile mentre una persona aspetta davanti a una schermata. È un pessimo modo per collegare due sistemi per giorni o settimane.

I Webhook consentono a CaptionBolt di avvisare il tuo endpoint HTTPS quando un progetto è pronto per il controllo, completato, non riuscito o annullato. Questo può spostare una scheda in una coda interna, avvisare la persona giusta o avviare il passaggio approvato successivo senza chiedere lo stato ogni pochi secondi.

Gli eventi sono firmati. Il ricevitore deve verificare la firma rispetto al corpo originale della richiesta, rifiutare i timestamp non più validi ed eliminare i duplicati in base all’ID evento prima di intervenire. Le consegne possono ripetersi o arrivare fuori ordine, quindi anche il ricevitore deve essere idempotente. Se una consegna non riesce, CaptionBolt riprova due volte — dopo circa un minuto e poi cinque minuti — prima di interrompere i tentativi automatici. Puoi controllare le consegne recenti e ripeterne una manualmente dopo aver corretto il ricevitore.

L’evento contiene i metadati del progetto, non il video. Un evento di completamento rimanda il tuo sistema all’endpoint autenticato del risultato, dove può richiedere un nuovo link per il download. Questa separazione mantiene piccola la notifica e lascia l’accesso sotto i permessi dell’API Key.

La guida ai Webhook spiega i tipi di evento, la verifica della firma, i nuovi tentativi, la rotazione dei segreti e come testare un endpoint prima di farvi affidamento.

MCP: lascia che un assistente AI usi gli strumenti, non che indovini le schermate

L’API pubblica è naturale quando uno sviluppatore ha già definito la sequenza. MCP è utile quando il passaggio successivo dipende da una conversazione.

MCP significa Model Context Protocol. Un assistente AI compatibile può collegarsi all’endpoint MCP in hosting di CaptionBolt e scoprire un insieme limitato di strumenti: elencare i progetti, controllare i limiti dell’account, trovare stili o preset, gestire una sessione di caricamento, creare un progetto, verificarne lo stato, richiedere un’esportazione, riprovare, annullare e recuperare un risultato.

Questo non significa dare a un agente un controllo illimitato.

Crei un’API Key dedicata in Settings → Integrations, scegli gli scope necessari e salvi la chiave nelle impostazioni segrete dell’host MCP, non in un prompt. L’host deve supportare MCP remoto su HTTP con un header Bearer. Le connessioni basate solo su OAuth non fanno parte di questa versione.

A quel punto l’istruzione può sembrare un normale accordo di lavoro:

Elenca i progetti CaptionBolt pronti per il controllo. Mostrami i tre più recenti e non esportare nulla finché non lo approvo.

L’assistente può decidere quale strumento chiamare dopo, ma CaptionBolt continua ad applicare gli scope dell’API Key, il piano attuale, la proprietà del progetto, i crediti e le transizioni di stato valide. Se la chiave non può esportare, una frase sicura del modello non cambia le cose.

È questo l’aspetto di MCP che ci interessa di più. Offre a un assistente un modo per lavorare con lo stato reale del progetto, invece di fingere di capire una dashboard da una descrizione. Dà anche al prodotto un confine netto: l’assistente può usare solo gli strumenti e i permessi che esponiamo.

Consulta la guida alla configurazione di MCP remoto per l’endpoint, i requisiti di connessione e un primo flusso con controllo prima dell’esportazione.

Tre ingressi, un solo insieme di regole

REST, Webhook e MCP risolvono problemi di coordinamento diversi:

• REST avvia il lavoro e legge lo stato dal software che controlli.
• Webhook avvisa quel software quando si verifica un evento importante del progetto.
• MCP consente a un assistente AI compatibile di scegliere tra gli stessi strumenti limitati durante una conversazione.

Alla base, tutti rispettano le stesse regole di progetto ed esportazione.

È stata una scelta architetturale e di prodotto. Una seconda pipeline riservata alle automazioni finirebbe per divergere dall’app su sottotitoli, crediti, proprietà del progetto, stato del controllo o esportazioni. Le integrazioni riutilizzano invece il flusso che abbiamo già trascorso mesi a rendere più resistente.

Questo significa anche che le integrazioni non aggirano i confini di CaptionBolt. L’API lavora sul materiale che hai già scelto. Non cerca clip virali in una lunga registrazione, non reinquadra automaticamente ogni persona, non doppia un video, non traduce i sottotitoli e non pubblica sulle piattaforme social. Anche le importazioni da URL remoti e la creazione autonoma di Transcripts non rientrano nella prima versione.

Questi limiti non sono note a piè di pagina. Sono ciò che ci permette di offrire un’automazione utile senza riaprire la raccolta di prodotti poco correlati che abbiamo scelto di ritirare.

Una buona prima automazione è noiosa

Il miglior primo test non è una macchina di contenuti completamente autonoma. È un video reale e un passaggio di consegne ripetuto.

Per esempio:

1. Crea un’API Key dedicata con accesso in lettura e scrittura ai progetti. Aggiungi i permessi di esportazione o Webhook solo se servono al flusso.
2. Carica un video noto e crea il progetto in modalità review.
3. Iscriviti all’evento che indica che il progetto è pronto, invece di controllare continuamente lo stato.
4. Apri il progetto in CaptionBolt, correggi la trascrizione e salva il risultato.
5. Richiedi l’esportazione dal tuo sistema, oppure chiedi a un assistente collegato di preparare l’azione e aspettare l’approvazione.
6. Ricevi l’evento di completamento, recupera un nuovo link al risultato e salva il file dove il tuo flusso si aspetta di trovarlo.

Quando questo percorso è affidabile, elimina il coordinamento manuale realmente ripetitivo. Conserva le decisioni di controllo che proteggono le parole, l’inquadratura e il risultato finale.

Per chi abbiamo costruito tutto questo

Il livello di integrazione è per chi sa già dove inserire CaptionBolt nel proprio processo.

Potrebbe essere uno sviluppatore che aggiunge video sottotitolati a un prodotto esistente, un’agenzia che collega l’ingresso dei clienti a una coda di controllo interna, un team che elabora lezioni in blocco o una persona che gestisce le operazioni e vuole far trovare il progetto giusto a un assistente AI senza cercare tra le schede.

Non è un requisito per usare CaptionBolt. Se completi un video alla volta, il browser resta la strada più semplice. L’API non dovrebbe trasformare un flusso breve in un progetto di sviluppo solo perché esiste un endpoint.

API pubblica, MCP remoto e Webhook sono disponibili per gli abbonati Max. Parti da Settings → Integrations, leggi la panoramica delle integrazioni e tieni a portata di mano la documentazione API mentre sviluppi.

Parti da un passaggio di consegne. Rendilo affidabile. Poi automatizza il successivo.