一个视频工作流，三种接入方式：Public API、Webhooks 与 MCP
我们为什么让应用、自动化流程和 AI Agent 都能接入 CaptionBolt，以及为什么它们仍然共用同一条可审核的字幕工作流。
Kevin Li
最初的 CaptionBolt 工作流完全在浏览器里完成。上传视频，等待转录，检查字幕，然后导出结果。
如果一次只处理一个视频，这仍然是最清楚的方式。但当同样的工作每天都要重复时，情况就不一样了。
课程团队可能一次录好五节课。代理机构可能希望客户的源文件一到，就立刻开始准备视频。开发者也可能已经有一套内部系统，知道哪段录制已经获批、该由谁审核，以及成片最终应该放在哪里。在多个标签页之间复制 ID 不是创意工作，不断刷新状态页也不是。
我们反复听到同一个问题的不同版本：CaptionBolt 能不能接进我们已经在用的工作流？
现在，我们的答案是可以。CaptionBolt 已经提供 Public API、签名 Webhooks，以及面向兼容 AI 助手的托管远程 MCP 服务。它们只是进入同一个产品的三种方式，而不是藏在技术名词后面的三个新视频产品。
浏览器不再是唯一入口
我们不想另外做一个“开发者版” CaptionBolt。
通过 Public API 创建的项目，与在应用里创建的项目使用同一个账户、处理分钟数、套餐限制、字幕样式、已保存预设和导出权限。一个项目可以从自动化流程开始，在 CaptionBolt 里暂停，交给人审核，再在修改保存后通过 API 继续执行。
最后这一点很重要。自动化应该减少重复协调，而不是悄悄拿走人的判断。
默认的集成模式是 review。CaptionBolt 会准备好转录稿和字幕，然后把项目留给人来检查。如果某条工作流确实不需要这一步，也可以使用 auto-export，但必须明确选择。
Public API：让明确的系统执行明确的工作
如果软件由你控制，REST API 是最直接的选择。
它可以读取账户限制，查找字幕样式和你保存的预设，分片续传视频，创建字幕项目，检查状态，请求导出，并获取最终结果。命令会迅速返回一个可继续跟踪的操作，而不是让一次请求在整个视频处理期间一直挂着。
我们也从第一版开始支持幂等。如果网络请求超时，你的系统可以用同一个幂等键重试同一个意图，不必猜测是否应该再创建一个项目。视频处理包含太多耗时步骤，不能把“连接关闭”简单理解为“什么都没发生”。
实际用法并不神秘。有人提交表单后，可以自动创建项目；内容日历可以把生成的项目 ID 写回现有记录；客户门户可以显示视频正在处理、等待审核、导出中，还是已经完成。你的系统负责协调，CaptionBolt 负责字幕工作流。
你仍然需要把 API Key 保存在服务端，只申请集成真正需要的 scope，并在结果访问窗口结束前保存成片。REST API 指南说明了从上传到获取结果的完整流程，实时的 API reference则提供请求和响应 schema。
Webhooks：真正有变化时再继续
当一个人盯着一个页面等待时，轮询还能派上用场。但如果要让两个系统持续连接几天甚至几周，它就不是一个好办法。
当项目进入等待审核、已完成、失败或已取消状态时，Webhooks 可以通知你的 HTTPS endpoint。这样，你可以移动内部队列里的卡片，提醒正确的编辑人员，或者启动下一个已经批准的步骤，而不必每隔几秒查询一次状态。
事件带有签名。接收端应该用原始请求正文验证签名，拒绝过期时间戳，并在开始工作前按 event ID 去重。投递可能重复，也可能不按顺序到达，所以接收端仍然必须保持幂等。投递失败后，CaptionBolt 会自动重试两次，大约分别在一分钟和五分钟后进行，之后停止自动尝试。修好接收端后，你可以查看近期投递记录，并手动重试其中一次。
事件里包含的是项目元数据，不是视频文件。完成事件会引导你的系统回到需要身份验证的结果 endpoint，在那里请求一个新的下载链接。这样既能让通知保持轻量，也能让访问继续受到 API Key 权限控制。
Webhooks 指南介绍了事件类型、签名验证、重试、密钥轮换，以及如何在真正依赖 endpoint 前完成测试。
MCP：让 AI 助手调用工具，而不是猜测屏幕
当开发者已经确定执行顺序时，Public API 很合适。当下一步要根据对话内容决定时，MCP 更有用。
MCP 是 Model Context Protocol 的缩写。兼容的 AI 助手可以连接 CaptionBolt 的托管 MCP endpoint，并发现一组边界明确的工具：列出项目、检查账户限制、查找样式或预设、管理上传 session、创建项目、检查状态、请求导出、重试、取消，以及获取结果。
这并不意味着把无限控制权交给 Agent。
你需要在 Settings → Integrations 中创建专用 API Key，选择它真正需要的 scope，并把 key 保存在 MCP host 的 secret settings 里，而不是写进 prompt。Host 必须支持带 Bearer header 的远程 HTTP MCP。本次发布不支持仅 OAuth 的连接方式。
然后，你可以像约定正常工作方式一样发出指令：
列出 CaptionBolt 中已经可以审核的项目。显示最新的三个，在我批准之前不要导出任何内容。
助手可以决定下一步调用哪个工具，但 CaptionBolt 仍然会执行 API Key scope、当前套餐、项目所有权、credits 和有效状态流转规则。如果 key 没有导出权限，模型再自信的一句话也改变不了这一点。
这正是 MCP 最吸引我们的地方。它让助手能够处理真实的项目状态，而不是根据一段描述假装自己看懂了 dashboard。它也为产品划出一条硬边界：助手只能使用我们明确开放的工具和权限。
你可以在远程 MCP 设置指南中查看 endpoint、连接要求，以及第一个“先审核、后导出”的工作流。
三个入口，同一套规则
REST、Webhooks 和 MCP 分别解决不同的协调问题：
- REST 从你控制的软件中发起工作并读取状态。
- Webhooks 在重要项目事件发生时通知该软件。
- MCP 让兼容的 AI 助手在对话中从同一组边界明确的工具里选择下一步。
在底层，它们遵守的是同一套项目和导出规则。
这是一个架构决定，也是一个产品决定。如果再做一条只供自动化使用的管线，它迟早会在字幕、credits、项目所有权、审核状态或导出方面与应用产生分歧。所以，集成层复用了我们已经花费数月时间打磨稳定性的工作流。
这也意味着，集成不会绕过 CaptionBolt 的产品边界。API 处理的是你已经选好的素材。它不会从长视频中寻找爆款片段，不会自动重新取景每个说话者，不会配音、翻译字幕或发布到社交平台。远程 URL 导入和单独创建 Transcript 也不在第一版范围内。
这些限制不是脚注。正因为有它们，我们才能提供真正有用的自动化，同时不重新打开那些已经主动收起、彼此关联不大的产品方向。
好的第一条自动化流程，通常很普通
最好的首次测试，不是一台全自动内容机器，而是一段真实视频和一次反复发生的交接。
例如：
- 创建一个专用 API Key，并授予项目读写权限。只有工作流确实需要时，才增加导出或 Webhook 权限。
- 上传一段已知视频，并用
review模式创建项目。 - 订阅 ready 事件，不要持续轮询。
- 在 CaptionBolt 中打开项目，修正转录稿并保存结果。
- 从你的系统请求导出，或者让已连接的助手准备这个操作并等待批准。
- 接收完成事件，获取新的结果链接，再把文件保存到工作流预期的位置。
当这条路径稳定之后，再移除那些确实只是重复劳动的人工协调。那些保护文字、画幅和最终结果的审核决定，应该继续保留。
我们为谁做了这套集成
集成层服务的是那些已经知道 CaptionBolt 应该放在流程哪个位置的人。
可能是把带字幕视频加入现有产品的开发者，可能是把客户 intake 接入内部审核队列的代理机构，也可能是批量处理课程视频的团队，或者不想在多个标签页里翻找，希望 AI 助手直接定位正确项目的运营人员。
使用 CaptionBolt 并不要求你一定要接 API。如果你一次处理一个视频，浏览器仍然是最简单的路径。不能因为有 endpoint，就把一条短流程变成一个工程项目。
Public API、远程 MCP 和 Webhooks 面向 Max 订阅用户开放。你可以从 Settings → Integrations 开始，阅读集成概览，并在开发时随时打开 API reference。
先选一次交接，把它做稳，再自动化下一步。
