Um fluxo de vídeo, três formas de entrar: API pública, Webhooks e MCP

O primeiro fluxo do CaptionBolt acontecia inteiro no navegador. Você enviava um vídeo, esperava a transcrição, revisava as legendas e exportava o resultado.

Essa ainda é a forma mais clara de finalizar um vídeo. Ela fica menos clara quando o mesmo trabalho acontece todos os dias.

Uma equipe de cursos pode gravar cinco aulas de uma vez. Uma agência pode precisar preparar os vídeos de um cliente assim que os arquivos originais chegam. Um desenvolvedor talvez já tenha um sistema interno que sabe qual gravação foi aprovada, quem precisa revisá-la e onde o arquivo final deve ficar. Copiar IDs entre abas não é trabalho criativo. Atualizar uma página de status sem parar também não.

Continuávamos ouvindo versões da mesma pergunta: o CaptionBolt pode entrar no fluxo que já usamos?

Agora a resposta é sim. O CaptionBolt tem uma API pública, Webhooks assinados e um servidor MCP remoto hospedado para assistentes de AI compatíveis. São três formas de entrar no mesmo produto, não três novos produtos de vídeo escondidos atrás de nomes técnicos.

O navegador não é mais a única porta de entrada

Não queríamos criar uma “versão para desenvolvedores” separada do CaptionBolt.

Projetos criados pela API pública usam a mesma conta, minutos de processamento, limites do plano, estilos de legenda, presets salvos e permissões de exportação dos projetos criados no aplicativo. Um projeto pode começar em uma automação, parar para uma pessoa revisá-lo no CaptionBolt e continuar pela API depois que as edições forem salvas.

Essa última parte importa. A automação deve remover a coordenação repetitiva sem tirar, silenciosamente, o julgamento humano.

O modo padrão da integração é review. O CaptionBolt prepara a transcrição e as legendas e deixa o projeto pronto para uma pessoa. auto-export está disponível quando um fluxo realmente não precisa dessa pausa, mas precisa ser escolhido de forma explícita.

API pública: trabalho previsível para sistemas previsíveis

A API REST é a opção direta para o software que você controla.

Ela pode consultar os limites da conta, encontrar estilos de legenda e seus presets salvos, enviar um vídeo em partes retomáveis, criar um projeto, verificar o status, solicitar uma exportação e obter o resultado final. Os comandos retornam rapidamente com uma operação para acompanhar, em vez de manter uma solicitação aberta durante todo o processamento do vídeo.

Também incluímos idempotência desde a primeira versão. Se uma solicitação de rede atingir o tempo limite, seu sistema pode repetir a mesma intenção com a mesma chave de idempotência, sem adivinhar se deve criar um segundo projeto. O processamento de vídeo tem etapas longas demais para “a conexão fechou” significar “nada aconteceu”.

Os casos de uso práticos não são exóticos. O envio de um formulário pode criar um projeto. Um calendário de conteúdo pode registrar o ID resultante em um item existente. Um portal do cliente pode mostrar se um vídeo está sendo processado, pronto para revisão, em exportação ou concluído. Seu sistema coordena; o CaptionBolt cuida do fluxo de legendas.

Ainda é sua responsabilidade manter a API Key no servidor, solicitar apenas os escopos necessários e salvar os arquivos finalizados antes que a janela de acesso termine. O guia da API REST explica toda a sequência, do envio ao resultado, e a referência da API ao vivo contém os schemas de solicitação e resposta.

Webhooks: continue quando algo realmente mudar

Consultar o status repetidamente é útil enquanto uma pessoa espera em uma tela. É uma forma ruim de conectar dois sistemas por dias ou semanas.

Os Webhooks permitem que o CaptionBolt avise seu endpoint HTTPS quando um projeto estiver pronto para revisão, concluído, com falha ou cancelado. Isso pode mover um cartão em uma fila interna, avisar o editor certo ou iniciar a próxima etapa aprovada sem perguntar pelo status a cada poucos segundos.

Os eventos são assinados. O receptor deve verificar a assinatura usando o corpo bruto da solicitação, rejeitar timestamps antigos e eliminar duplicatas pelo ID do evento antes de agir. As entregas podem se repetir ou chegar fora de ordem, então o receptor também precisa ser idempotente. Quando uma entrega falha, o CaptionBolt tenta novamente duas vezes — depois de cerca de um minuto e de cinco minutos — antes de interromper as tentativas automáticas. Você pode consultar as entregas recentes e repetir uma manualmente depois de corrigir o receptor.

O evento contém metadados do projeto, não o vídeo. Um evento concluído direciona seu sistema de volta ao endpoint autenticado do resultado, onde ele pode solicitar um novo link de download. Essa separação mantém a notificação pequena e o acesso sob as permissões da API Key.

O guia de Webhooks explica os tipos de evento, a verificação de assinatura, as novas tentativas, a rotação de segredos e como testar um endpoint antes de depender dele.

MCP: deixe um assistente de AI usar ferramentas, não adivinhar telas

A API pública é uma escolha natural quando um desenvolvedor já definiu a sequência. O MCP é útil quando a próxima etapa depende de uma conversa.

MCP significa Model Context Protocol. Um assistente de AI compatível pode se conectar ao endpoint MCP hospedado do CaptionBolt e descobrir um conjunto limitado de ferramentas: listar projetos, consultar limites da conta, encontrar estilos ou presets, gerenciar uma sessão de envio, criar um projeto, verificar o status, solicitar uma exportação, tentar novamente, cancelar e obter um resultado.

Isso não significa dar controle ilimitado a um agente.

Você cria uma API Key exclusiva em Settings → Integrations, escolhe os escopos necessários e guarda a chave nas configurações secretas do host MCP — não em um prompt. O host precisa oferecer MCP remoto por HTTP com um cabeçalho Bearer. Conexões somente por OAuth não fazem parte desta versão.

Então a instrução pode soar como um acordo normal de trabalho:

Liste os projetos do CaptionBolt que estão prontos para revisão. Mostre os três mais recentes e não exporte nada até eu aprovar.

O assistente pode decidir qual ferramenta chamar depois, mas o CaptionBolt ainda aplica os escopos da API Key, o plano atual, a propriedade do projeto, os créditos e as transições de estado válidas. Se a chave não pode exportar, uma frase confiante do modelo não muda isso.

Essa é a parte do MCP que mais nos interessa. Ele permite que um assistente trabalhe com o estado real do projeto, em vez de fingir que entende um dashboard a partir de uma descrição. Também dá ao produto um limite rígido: o assistente só pode usar as ferramentas e permissões que disponibilizamos.

Consulte o guia de configuração do MCP remoto para ver o endpoint, os requisitos de conexão e um primeiro fluxo de revisão antes da exportação.

Três entradas, um conjunto de regras

REST, Webhooks e MCP resolvem problemas diferentes de coordenação:

• REST inicia o trabalho e lê o estado a partir do software que você controla.
• Webhooks avisam esse software quando acontece um evento importante no projeto.
• MCP permite que um assistente de AI compatível escolha entre as mesmas ferramentas limitadas durante uma conversa.

Por baixo, todos seguem as mesmas regras de projeto e exportação.

Essa foi uma decisão de arquitetura e de produto. Um segundo pipeline exclusivo para automação acabaria divergindo do aplicativo em legendas, créditos, propriedade do projeto, estado de revisão ou exportações. Por isso, as integrações reutilizam o fluxo que passamos meses tornando mais resistente.

Isso também significa que as integrações não contornam os limites do CaptionBolt. A API trabalha com o material que você já escolheu. Ela não procura clipes virais em uma gravação longa, não reenquadra automaticamente cada pessoa, não dubla vídeos, não traduz legendas nem publica em redes sociais. Importações por URL remota e a criação independente de Transcripts também estão fora da primeira versão.

Esses limites não são notas de rodapé. São eles que permitem oferecer uma automação útil sem reabrir a coleção de produtos pouco relacionados que decidimos aposentar.

Uma boa primeira automação é sem graça

O melhor primeiro teste não é uma máquina de conteúdo totalmente autônoma. É um vídeo real e uma passagem de trabalho que se repete.

Por exemplo:

1. Crie uma API Key exclusiva com acesso de leitura e gravação a projetos. Adicione permissões de exportação ou Webhooks apenas se o fluxo precisar delas.
2. Envie um vídeo conhecido e crie o projeto no modo review.
3. Assine o evento de pronto em vez de consultar o status continuamente.
4. Abra o projeto no CaptionBolt, corrija a transcrição e salve o resultado.
5. Solicite a exportação pelo seu sistema — ou peça a um assistente conectado para preparar a ação e aguardar aprovação.
6. Receba o evento de conclusão, obtenha um novo link do resultado e salve o arquivo onde seu fluxo espera encontrá-lo.

Quando esse caminho estiver confiável, retire a coordenação manual que for realmente repetitiva. Preserve as decisões de revisão que protegem as palavras, o enquadramento e o resultado final.

Para quem criamos isso

A camada de integrações é para quem já sabe onde o CaptionBolt entra em seu processo.

Pode ser um desenvolvedor adicionando vídeo com legendas a um produto existente, uma agência conectando a entrada de clientes a uma fila interna de revisão, uma equipe de cursos processando aulas em lote ou uma pessoa de operações que quer que um assistente de AI encontre o projeto certo sem vasculhar abas.

Ela não é um requisito para usar o CaptionBolt. Se você finaliza um vídeo por vez, o navegador continua sendo o caminho mais simples. A API não deve transformar um fluxo curto em um projeto de engenharia só porque existe um endpoint.

A API pública, o MCP remoto e os Webhooks estão disponíveis para assinantes Max. Comece em Settings → Integrations, leia a visão geral das integrações e mantenha a referência da API por perto enquanto desenvolve.

Comece com uma passagem de trabalho. Torne-a confiável. Depois automatize a próxima.