用Google Apps Script和Supadata自动转录并总结YouTube视频

手动观看每一个YouTube视频再写摘要，根本无法规模化。原文作者在iadots.com上以四种语言汇集AI、智能体、机器人与人形机器人相关视频，为此搭建了一套无服务器的自动化流程：用Google Apps Script调用Supadata API抓取字幕，交给大语言模型生成摘要，再写回Google表格。整套方案只有一百多行代码，却包含了生产环境里值得借鉴的工程细节。

整体思路与前置条件

这套自动化把一张Google表格当作视频队列来用。表格里有一个名为Videos的工作表，包含三列：youtubeId（URL中v=后面的视频ID）、lang（视频原始语言，如en或pt）、以及初始为空的resumo（摘要列）。脚本定时扫描这张表，为每一条还没有摘要的记录补上内容。

要跑通流程，你需要准备三样东西：一个Google账号用于使用Apps Script和Sheets；一把Supadata的API密钥（免费套餐足够测试）；以及一把在Google AI Studio生成的Gemini API密钥。作者强调，Gemini可以替换成其他模型，只要相应调整摘要函数即可。项目可以在表格的「扩展程序 > Apps Script」里创建，也可以直接去script.google.com新建。

密钥管理：绝不写进代码

第一个工程习惯就是把密钥从代码里剥离出来。作者的做法是在Apps Script编辑器的「项目设置 > 脚本属性」中创建SUPADATA_API_KEY和GEMINI_API_KEY两个属性，脚本在运行时通过PropertiesService.getScriptProperties()读取。

配套的chave()辅助函数在读取时顺带做了存在性校验——一旦属性缺失就直接抛出异常，而不是让后续请求带着空密钥去撞墙。这种「fail fast」的小设计，在无人值守的定时任务里能省去不少排查时间。全局常量里还预设了LIMITE_BYTES = 180000，为后面控制文本体积埋下伏笔。

PropertiesService 是 Google Apps Script 提供的键值存储服务，分为脚本级（Script）、用户级（User）和文档级（Document）三个作用域。脚本级属性对所有运行该脚本的用户可见，适合存储 API 密钥这类全局配置。与直接硬编码相比，它的核心优势在于：属性值不随代码版本进入 Git 历史，即便项目被分享或部署到他人账号，密钥也不会随源码一起暴露。「fail fast」原则指让程序在遇到无效状态时尽早崩溃、给出明确错误，而不是带着错误数据继续执行直到在某个难以定位的位置出错。对于定时无人值守任务而言，一次明确的启动失败远比一次沉默的错误执行更容易发现和修复。

转录函数的三个关键参数

抓取字幕调用的是GET /v1/transcript端点，认证走x-api-key请求头。作者用了三个关键参数：mode=native只取视频已有的字幕，不触发AI生成转录；text=true返回连续文本而非带时间戳的片段；lang指定原始语言。

这里藏着一个容易踩坑的文档细节：如果请求的语言不存在，Supadata会返回第一个可用的语言。为避免一个日语视频被错误地喂进一段翻译字幕，脚本会校验返回结果里的lang字段，与请求语言不一致时直接丢弃结果（返回idioma_ou_texto_indisponivel）。这个判断看似多余，却是保证四语言内容互不串台的关键。

对于超长视频，接口可能返回状态码202和一个jobId，这时需要轮询GET /v1/transcript/{jobId}直到状态变为completed或failed。作者的aguardarJob函数做了最多12次、每次间隔5秒的轮询，兼顾了异步任务的等待与超时保护。而180000字节的上限则是出于现实考量：过长的转录会让摘要变慢变贵，还可能撑爆Apps Script的执行时限。

HTTP 202 状态码在 REST API 设计规范中表示「请求已被接受，但处理尚未完成」，常用于耗时较长的异步任务。与之配合的轮询模式（Polling）是最简单的异步结果获取方式：客户端按固定或递增间隔反复查询任务状态，直到得到终态（成功或失败）。相对的替代方案是 Webhook 回调，即由服务端在任务完成时主动推送结果，省去轮询开销，但需要客户端暴露一个可被外部访问的回调地址。Apps Script 本身没有长驻进程，无法接收 Webhook，因此轮询是唯一可行选择。12 次 × 5 秒 = 60 秒的等待上限，在 Apps Script 单次执行约 6 分钟的时限内为处理多个视频留出了余量。

摘要生成：让密钥远离日志

摘要环节调用Gemini的generateContent方法，同样直接用UrlFetchApp发请求。一个细节是密钥放在x-goog-api-key请求头而非URL里，目的是避免密钥出现在日志中——这是对前面「密钥不入代码」原则的延续。

在payload设计上，作者用systemInstruction明确要求模型「忠实总结科技视频转录，不编造信息」，generationConfig里把temperature压到0.3以减少发散。提示词要求输出3到5句话，并且用视频原始语言生成，这样每个语种版本的站点才能保持内容一致。解析响应时还特意过滤掉了带thought标记的部分，只保留真正的文本输出，这是对接新一代推理型模型时的实用处理。

幂等设计：避免重复消耗额度

这是作者最在意的一环。假如调用Supadata的请求在中途超时，脚本无法确认额度是否已经扣掉；若下一轮执行时无脑重试，就可能为同一个视频付两次钱。

解决方案是在发起请求之前，先在PropertiesService里写入一个标记（TX_DONE_{youtubeId}_{lang}）。如果标记已存在，该视频直接跳过；标记在finally块里被更新为最终结果——成功写resumido，失败写具体原因。这意味着一旦转录成功而摘要失败，视频会被标记为erro停在原地，需要人工查看原因并手动删除属性才会重试。作者坦言这是一个有意识的取舍：「我宁愿手动复查一个案例，也不愿不知不觉地付两次钱。」在成本敏感的API调用场景里，这种以幂等换安全的思路很有参考价值。

幂等性（Idempotency）是分布式系统和 API 设计中的核心概念，指对同一操作执行多次与执行一次的效果完全相同。在网络请求场景下，客户端往往无法区分「服务端已处理但响应丢失」与「服务端未收到请求」这两种超时情形，盲目重试就可能导致重复计费或数据重复写入。常见的工程应对手段包括：使用唯一请求 ID 让服务端自行去重、在客户端维护本地状态标记（即本文采用的方案）、以及选用天然支持幂等的 HTTP 方法（如 PUT 代替 POST）。本文将标记写入时机提前到请求发出之前，属于「先占位再操作」的保守策略，以牺牲少量可重试性换取零重复付费的确定性，在外部付费 API 的调用场景中是合理的工程取舍。

定时触发与并发控制

最后，主函数rodarAutomacao每次只处理5个视频，并用一个每小时执行一次的时间触发器驱动。LockService.getScriptLock()则保证两次执行不会同时运行、抢到同一个视频。只处理5个的限制同样源于Apps Script每次执行只有几分钟的时间上限。

criarGatilho函数在创建新触发器前会先清掉同名的旧触发器，避免重复注册。手动执行一次criarGatilho并授权权限后，表格里每新增一行，最多一小时就会自动得到摘要。

常见错误与排错建议

作者还总结了几类高频问题：出现状态码206或transcript-unavailable，说明该视频没有所请求语言的字幕——在mode=native下这是预期行为，若想覆盖这些情况可以尝试mode=auto让AI生成转录，但要先确认额度消耗；语言代码要用ISO 639-1标准（en、pt、es），脚本已自动忽略-BR这类后缀；PropertiesService有存储配额，建议只存状态，摘要本身放表格或数据库。

整套方案证明了一点：不需要服务器、不需要基础设施成本，一百多行Apps Script就能把一份视频清单变成可直接发布的多语言摘要。真正拉开差距的，是那三个工程细节——校验返回语言、限制文本体积、以及在消耗额度前先打标记。

注：原文含Supadata的推荐链接，作者声明可能因注册获得额度返利。