制作开发者真正愿意看的 API 文档视频

书面的 API 参考文档精确而完整，却几乎无法作为起点。开发者打开端点列表，知道每个字段的含义，却完全不知道真正开始使用这个 API 的头五分钟是什么样子。

一段简短的视频正好填补这个空白。它不是参考文档的替代品，而是搭档。三分钟展示一把真实的密钥、一个真实的请求和一个真实的响应，回答了文档无法回答的问题：它真的像我以为的那样工作吗?

下面是把这类视频拍得长期有用的方法。

先决定什么值得拍成视频

视频的维护成本很高，要把它用在文字最薄弱的地方。

• 第一次成功调用：从空白终端到 200 响应。这是你能做的最有价值的一支视频
• 认证流程：OAuth 跳转、令牌交换和刷新逻辑都是”顺序”。顺序正是视频擅长的
• 多步骤工作流：创建资源、轮询状态、获取结果。在参考文档里它们看起来是三个互不相关的端点
• Webhook 与回调：两个系统互相通信的过程，用文字描述实在太难
• 常见错误：一段展示 401 以及如何修复的视频，比一整段文字减少的工单更多

不值得拍成视频的：单个端点的参数、枚举值、限流数字。这些应该留在文本里，方便搜索、复制，几秒钟就能更新。

准备一个录制沙盒

绝不要拿真实密钥对着生产环境录制。按下录制键之前先搭好专用环境。

• 使用一次性沙盒账号，录完立刻轮换密钥
• 填入真实感数据：test_user_1 和 "foo" 会让演示显得虚假。可信的姓名、金额和时间戳会让观众信任这个 API
• 优先选择短期有效的密钥格式，这样即使某一帧露出令牌也无害
• 检查你的 shell 环境：env 的输出和命令历史泄露过的凭证，比任何代码示例都多
• 提前预热缓存和依赖，别把安装过程录进去
• 关闭通知 —— 公开视频里弹出的 Slack 预览是真实发生过的事故

即便是沙盒，也要当作每一帧都会被公开。总会有人按下暂停。

选择合适的捕获方式

API 演示通常涉及两三个界面：终端、编辑器、Postman 或 Insomnia 这类 API 客户端，有时还有用于控制台的浏览器。

• 对每个界面使用窗口捕获，画面更紧凑，也遮住了杂乱的桌面
• 如果必须切换应用，请提前并排摆好，然后用区域捕获把两者都框进去。录制中来回切窗口会让观众迷失
• 文字为主的内容 30fps 足够，更低的帧率能把码率留给更清晰的字符
• 按原生分辨率录制 —— 事后放大正是模糊的来源
• 把字号调到 18–24pt。在显示器上看起来夸张的大小，在视频里刚刚好

让每段视频结构一致

有了一致性，它才像”文档”，而不是一堆零散的录屏。一个可靠的四段式结构：

1. 用一句话说明目标：“我们要创建一个客户并向他收费。”
2. 展示认证：哪怕只有一个请求头也要展示。观众需要看到密钥放在哪里
3. 现场构造请求：手敲或粘贴，并逐个字段讲解。说清楚每个参数为什么存在
4. 把响应读出来：在 JSON 上停一下，指出下一步要用到的字段

最后预告下一步：“这个 id 就是我们收费时要用的 —— 那是下一支视频的内容。“

让 JSON 和代码易读

多数 API 视频正是栽在这里。请求成功了，响应铺满屏幕，观众看到的却是一堵读不懂的大括号墙。

• 一律格式化输出：用 jq 管道处理，或打开客户端的格式化功能
• 折叠无关内容：大多数 API 客户端支持折叠区块，把没人关心的元数据折起来
• 对关键字段做缩放：给关键的两行加一个缩放效果，胜过任何解说。在 Recorded 里，你可以录完之后在编辑器中添加缩放，这样录制时只需专注于把调用做对
• 用文字叠加标注字段名：一个指向 subscription_status 的标签，比用嘴说读得更快
• 剪掉等待：网络延迟、轮询循环和重新构建都是空白时间。剪掉它们，用一行简短字幕交代经过了多久

像同事一样讲解，而不是像规范文档

正式的描述参考页里已经有了。你的旁白应该说出文档说不出的话：

• “这个请求头就是大家最常忘记的那个。”
• “是的，这个字段看起来可选，其实必填。”
• “如果这里报 422，几乎总是日期格式的问题。”

这类评论才是文档视频真正的产出。录制前先写下三四条 —— 一旦专注于正确敲代码，它们很容易被忘掉。

保持短小且模块化

一支二十分钟的”API 完整导览”，只要有一个端点变动就彻底作废。聚焦单一任务的两到四分钟短片寿命长得多，而且可以嵌在它所解释的那一节参考文档旁边。

模块化也意味着易于重录。当请求体结构变化时，你只需重录一段九十秒的短片，而不是围着一支长视频做手术。

为 API 的变化做好准备

文档视频比文档文字老化得更快，一开始就把这点考虑进去：

• 口头和画面上都标明版本号，让过期的视频一眼就能看出过期
• 尽量避开容易过时的界面元素 —— 控制台改版让视频显老的速度，比 API 变更还快
• 保留原始录制和工程文件，而不只是导出成品，这样重新编辑不等于重新拍摄
• 按端点和版本命名文件，发布之后能马上找到需要更新的内容
• 每次大版本升级时复查所有短片，把已经说错的重录一遍

上个季度拍的、简短而诚实的视频没有问题。但一支信心十足地展示着早已不存在的端点的视频，会让你失去信任。

发布在问题产生的地方

位置最好的 API 视频，是直接嵌在该端点参考页里的那一支，而不是躺在没人访问的独立视频库中。超过两分钟就加上章节或时间戳，在播放器下方附上视频中完整、可复制的代码，并把成功响应的片段导出成简短 GIF 放到快速上手页。

快速清单

• 使用一次性密钥的沙盒账号
• 真实感的预置数据
• 关闭通知，清理命令历史
• 放大字号，摆好窗口
• 目标 → 认证 → 请求 → 响应结构
• 格式化的 JSON，对关键字段缩放
• 剪掉等待时间
• 画面上标明版本
• 嵌入对应的参考章节旁
• 视频旁附上可复制的代码

参考文档告诉开发者什么是可能的。一段好的录制让他们看到它确实能跑通 —— 而这通常就是把他们送到第一次成功调用的那一步。