knowledge-work-plugins 中的 Zoom AI Services Scribe 转录实战指南JWT 认证、Fast/Batch 双模式与浏览器麦克风伪流式架构【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins本篇技术指南以开源仓库 knowledge-work-plugins 中 scribe 技能 及其配套子文档为核心完整讲解 Zoom AI Services Scribe 文件/存储转录服务的落地方法从 Build-platform JWT 签发、Fast Mode 同步转录与 Batch 异步批处理两条主链路到浏览器麦克风伪流式方案、Webhook 驱动的状态通知以及围绕版本漂移的排障与预检 Runbook。读完本文你将能独立搭建一条可运行的上传转录代理、批量 S3 转录与 Webhook 回写流水线并掌握 9 类高频故障的定位方法。Scribe 是什么文件/存储转录服务的定位与路由护栏Scribe 是 Zoom AI Services 家族中面向已上传或已存储媒体的转录服务核心能力是把音频/视频文件转成带时间戳、声道与说话人信息的文本。它与 Zoom 的实时媒体流服务 RTMS 边界清晰Scribe 处理「文件」RTMS 处理「直播流」。在 scribe 技能入口 中定义了四条路由护栏用于避免产品选错用户诉求路由目标上传或存储的媒体需要转成文本先路由到scribe需要实时会议媒体非文件上传/批处理转 rtms 技能需要 Zoom REST API 的 AI Services 路径清单串联 rest-api 技能需要 Webhook 签名模式或通用 HMAC 接收加固可选串联 webhooks 技能Scribe 覆盖的能力面包括同步单文件转录POST /aiservices/scribe/transcribe异步批量作业/aiservices/scribe/jobs*基于重复短文件上传的浏览器麦克风伪流式转录由 Webhook 驱动的批量状态更新Build-platform JWT 签发与凭据处理认证模型Build-platform JWT 与凭据命名漂移HS256 JWT 结构Scribe 使用Build-platform JWT Bearer Token认证而非 OAuth。JWT 的三要素算法HS256issueriss声明Build-platform 凭据标识符Scribe API 用它识别调用方过期时间exp保持在一小时或更短认证与处理模式文档 给出了 Node.js 侧的最小签发实现基于jsrsasign的KJURimport { KJUR } from jsrsasign; export function generateJWT(apiKey, apiSecret) { const iat Math.round(Date.now() / 1000) - 30; const exp iat 60 * 60; return KJUR.jws.JWS.sign( HS256, JSON.stringify({ alg: HS256, typ: JWT }), JSON.stringify({ iss: apiKey, iat, exp }), apiSecret, ); }注意iat回拨了 30 秒这是为时钟偏差留的缓冲exp设为iat 3600一小时。凭据命名漂移API Key 还是 SDK KeyZoom 官方文档在不同页面使用了不一致的命名AI Services 认证页API key/API secretBuild-platform 凭据页SDK key/SDK secretQuickstart 示例代码ZOOM_API_KEY/ZOOM_API_SECRET版本漂移文档 明确指出实现时统一把它们当作 Build-platform 的 JWT issuer/secret 对但在上线前务必到当前门户 UI 核实确切的字段标签。环境变量约定环境变量文档 给出了完整的配置面JWT 认证必填变量必填说明ZOOM_API_KEY是Build-platform issuer key用于 JWTiss声明ZOOM_API_SECRET是HS256 签名的 Build-platform secret通用应用变量变量必填说明PORT否本地服务端口LANGUAGE否默认语言代码如en-USBatch / S3 变量变量必填batch 场景说明S3_INPUT_URI通常输入前缀或文件 URIS3_OUTPUT_URI通常输出转录目的地AWS_ACCESS_KEY_ID未使用预签名访问时需要AWS 凭据AWS_SECRET_ACCESS_KEY未使用预签名访问时需要AWS 凭据AWS_SESSION_TOKEN常需要临时凭据令牌Webhook 变量变量必填说明WEBHOOK_URL可选接收批量通知的公网 HTTPS 回调WEBHOOK_SECRET可选但推荐校验 Zoom 回调签名的 HMAC secret关键坑不要把${ZOOM_API_KEY}这类 shell 占位符当作有效配置值。占位符会让健康检查「看起来已配置」但每次真实调用都会失败——这是文档与 Runbook 反复强调的失败模式。处理模式Fast Mode 与 Batch Mode 的选择认证与处理模式文档 对两种模式做了精确定位模式适用场景传输方式结果时机Fast mode单个短文件、交互式 UXPOST /transcribe立即返回同步 JSONBatch mode归档、长媒体、大量文件POST /jobs后查状态/等 Webhook异步选择 Fast mode 的条件用户只上传一个文件延迟比吞吐量更重要文件大小与时长可控在做基于短麦克风分片的浏览器伪流式选择 Batch mode 的条件需要处理大量文件转录结果可以稍后到达存储中心化工作流比直传更契合端点清单与请求/响应形状端点总览API 参考文档 基于 AI Services OpenAPI 清单api-hub/ai-services/methods/endpoints.json基础 URL 为https://api.zoom.us/v2MethodEndpoint说明Operation IDPOST/aiservices/scribe/transcribeScribe 同步转录createFastAsrPOST/aiservices/scribe/jobs提交批量 Scribe 作业submitBatchAsrGET/aiservices/scribe/jobs列出批量作业listBatchJobsGET/aiservices/scribe/jobs/{jobId}查询批量作业状态getBatchJobStatusDELETE/aiservices/scribe/jobs/{jobId}取消排队/处理中的作业cancelBatchJobGET/aiservices/scribe/jobs/{jobId}/files查看每个文件的转录结果listBatchJobFilesFast Mode 请求形状必填顶层字段file、config常见 config 字段认证与处理模式文档字段作用language语言代码如en-USword_time_offsets是否输出逐词时间偏移channel_separation是否按声道分离立体声通话录音timestamps时间戳output_format输出格式profanity_filter粗话过滤diarization说话人分离/区分响应关键键request_id、duration_sec、model、resultBatch Mode 请求形状必填顶层字段input、output、configinput 子字段modeSINGLE/PREFIX/MANIFESTsource当前 OpenAPI 中为S3uri/manifestfilters.include_globs、filters.exclude_globs均最多 10 项auth.aws.access_key_id/secret_access_key/session_tokenoutput 子字段destination、urilayoutSINGLE/PREFIX/ADJACENTauth.aws.*config 子字段language、word_time_offsets、channel_separation、diarization、profanity_filter、output_format、segmentation_mode可选字段reference_id、notifications.webhook_url、notifications.secret提交响应键job_id、state、submitted_at查询与状态端点GET /jobs查询参数state、page_size、next_page_token响应键jobs、next_page_tokenGET /jobs/{jobId}响应键job_id、state、submitted_at、summaryGET /jobs/{jobId}/files查询参数page_size、next_page_token响应键files、next_page_token当前限制与约束来自源文档Batch manifest 上限1000 个文件 URIinclude_globs最多10项exclude_globs最多10项文档标注的媒体格式WAV、MP3、M4A、MP4Fast mode 正式上限100 MB文件、2 小时时长OpenAPI 描述中批量作业的速率限制标签为LIGHT实战一Fast Mode 同步转录Node/Express 代理Fast Mode Node 示例 提供了一个可直接复用的最小后端代理。核心思路前端上传文件 → 后端签 JWT → 转发 multipart 到 Zoom → 回传转录 JSON。import express from express; import multer from multer; import { KJUR } from jsrsasign; const app express(); const upload multer({ storage: multer.memoryStorage() }); app.use(express.json()); function generateJWT() { const iat Math.round(Date.now() / 1000) - 30; const exp iat 60 * 60; return KJUR.jws.JWS.sign( HS256, JSON.stringify({ alg: HS256, typ: JWT }), JSON.stringify({ iss: process.env.ZOOM_API_KEY, iat, exp }), process.env.ZOOM_API_SECRET, ); } app.post(/transcribe, upload.single(file), async (req, res) { const token generateJWT(); const config { language: req.body.language || en-US, word_time_offsets: true, channel_separation: false, }; let response; if (req.file) { const form new FormData(); form.append(file, new Blob([new Uint8Array(req.file.buffer)]), req.file.originalname); form.append(config, JSON.stringify(config)); response await fetch(https://api.zoom.us/v2/aiservices/scribe/transcribe, { method: POST, headers: { Authorization: Bearer ${token} }, body: form, }); } else { response await fetch(https://api.zoom.us/v2/aiservices/scribe/transcribe, { method: POST, headers: { Authorization: Bearer ${token}, Content-Type: application/json, }, body: JSON.stringify({ file: req.body.file, config, }), }); } const text await response.text(); res.status(response.status).type(application/json).send(text); });该示例同时演示了 fast mode 的两种合法提交形态务必按服务边界选一种清晰的模型形态提交方式适用场景调用方上传文件到你的后端后端以multipart/form-data转发FormData携带fileconfig字符串浏览器/客户端直传调用方已有 URL 可访问的媒体后端以 JSON body 提交file字段放 URL服务端已存文件样例验证文档 补充了关键实现细节multer的 memory storage 对小型 fast mode 演示足够官方 quickstart 也证明「即使文档展示的是 JSON 示例fast mode 同样可以在你的服务器上以 multipart 上传处理方式代理」。实战二Batch 作业 Webhook 流水线端到端流程Batch 作业 Webhook 流水线示例 给出的链路为submit batch job - receive job_id - poll /jobs or wait for webhook - inspect /jobs/{jobId}/files - ingest transcript outputs提交示例curlcurl -X POST https://api.zoom.us/v2/aiservices/scribe/jobs -H Authorization: Bearer $TOKEN -H Content-Type: application/json -d { input: { mode: PREFIX, source: S3, uri: s3://example-bucket/audio/, auth: { aws: { access_key_id: ..., secret_access_key: ..., session_token: ... } } }, output: { destination: S3, uri: s3://example-bucket/transcripts/, layout: PREFIX, auth: { aws: { access_key_id: ..., secret_access_key: ..., session_token: ... } } }, config: { language: en-US, word_time_offsets: true, channel_separation: true }, notifications: { webhook_url: https://example.com/webhooks/scribe, secret: replace-me } }要点input.modePREFIX表示处理uri前缀下的全部匹配文件output.layoutPREFIX表示转录结果按源前缀镜像落盘AWS 凭据直接注入请求载荷——样例验证文档 指出这是 quickstart 的常规做法但生产流水线更建议使用预签名 URL 或短时 STS 临时凭据不要把长期 AK/SK 写进请求体。Webhook 签名验证Zoom 回调用的是x-zm-signaturex-zm-request-timestamp头HMAC-SHA256 计算后带sha256前缀。验证实现import crypto from crypto; function verifyZoomWebhook(rawBody, timestamp, signature, secret) { const message v0:${timestamp}:${rawBody}; const expected sha256${crypto.createHmac(sha256, secret).update(message).digest(hex)}; return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected)); }验证失败时按顺序排查raw body 是否在 JSON 解析前捕获、时间戳头是否纳入签名串、共享 secret 是否与作业的notifications.secret一致。浏览器麦克风伪流式模式Scribe 不暴露文档化的实时流 API因此浏览器麦克风体验必须建模为重复的短文件上传而不是一条长连接流。推荐的模式用MediaRecorder捕获浏览器麦克风音频按短分片 flush 到你的后端每个分片通过异步 fast mode 包装器提交按请求 ID 轮询完成状态按顺序拼接各分片转录结果推荐起始节奏分片大小5 秒可接受范围5-10 秒同时在途分片请求2-3个该模式的适用边界认证与处理模式文档 的护栏它本质上是「基于文件上传的伪流式」它不是实时音频捕获的首选生产设计仅当轻量浏览器演示或粗略的增量转录可接受时使用需要稳定低延迟实时转录、更低开销、跨语句强连续性时应避免真正的直播媒体流、低延迟服务端摄入或会议中连续音频改用 rtms高等级应用场景场景文档 给出了六类落地场景覆盖了从交互式单文件到离线合规处理的全谱系场景 1按需上传转录Fast mode浏览器上传 → 后端签发 Build JWT → 调用POST /aiservices/scribe/transcribe→ 返回转录 JSON。下游用途通话后摘要、工单充实、可检索片段库、内部审阅/交接笔记。场景 2批量 S3 归档转录Batch mode构建带输入前缀与输出前缀的批量请求 → 提交POST /aiservices/scribe/jobs→ 通过 Webhook 或轮询跟踪状态 → 读/jobs/{jobId}/files获取逐文件成败 → 导入搜索、分析或存储。下游用途合规与审计日志、可检索的网络研讨会/播客归档、批量转录回填、QA 评分输入。场景 3Zoom 录音导出后重新转录技能链zoom-rest-api拉取/下载录音 scribe转录导出媒体。典型动机自建留存/搜索管线、需要不同于 Zoom 托管默认的转录设置、用自建摘要/打标流程增强录音。场景 4合规 / QA 处理Batch mode离线生成用于审计、QA 评分或归档搜索的转录。优先项审阅者需要精确摘录时word_time_offsetstrue立体声通话录音用channel_separationtrue大流量下用 Webhook 队列摄入而非同步轮询。场景 5客服语音到洞察流水线录音入库 →scribe转录 → 存储转录文本及说话人/时间元数据 → 下游自建情绪、关键词、升级、QA 逻辑。护栏Scribe 只做转录情绪分析、关键词检测、评分全部放到转录生成后的下游服务。场景 6浏览器麦克风增量转录浏览器MediaRecorder捕获 → 每5 秒flush 一个分片 → 后端把每个分片当作普通 fast mode 上传经异步包装器提交 → 前端按请求 ID 轮询并按序拼接。护栏这是重复文件上传的伪流式最适合轻量演示或受限兜底真正的实时转录产品优先走rtms。故障排查与 5 分钟预检 Runbook九类高频故障速查常见漂移与故障文档 系统梳理了 9 类问题凭据看似正确但认证失败核对iss值、exp窗口、门户当前凭据标签确认不是把非 Build 应用凭据混用。若 API 返回{code:124,message:Invalid Access token}这是真实的上游认证失败而非传输问题。Fast mode 请求形状不匹配上传文件与 URL 文件是两条独立请求路径不要强行用单一 JSON 形态承载。症状是浏览器请求长时间挂起、后端最终超时或空响应。413 Request Entity Too Large通常是反向代理在请求到达应用前就拒绝了上传。nginx 前置时需把client_max_body_size抬到不低于服务端上传上限。504 Gateway time-out请求已到后端但同步处理超过边缘/代理路径时长。部署观测显示约 17.2 MB MP4 约 26s 完成约 38.6 MB 约 26-37s约 59.2 MB 约 32-34s后端但部分约 59.2 MB 浏览器请求先以504超时而后端日志显示200。前端 504 后端 200 浏览器/边缘超时竞态不是转录失败。建议为请求级日志记录文件名、大小、mime、上游耗时、响应载荷大小与顶层键托管 UI 用异步请求/轮询包装器若 nginx 访问日志出现499而应用日志稍后显示zoom_request_finished status: 200说明转录已成功、只是浏览器侧请求路径丢失。批量作业被接受但输出永不出现检查 S3 URI/认证不匹配、STS 凭据过期、输出 layout/URI 不匹配、依赖回调时 Webhook 端点不可达核对/jobs/{jobId}摘要与/jobs/{jobId}/files及云存储权限。Webhook 验证失败确认 raw body 捕获先于 JSON 解析、时间戳头纳入签名串、共享 secret 与作业通知配置一致。健康检查说凭据存在但 API 调用仍失败环境文件里多半是${ZOOM_API_KEY}这类字面占位符。只把真实值视为已配置并在调用 Zoom 前以明确的凭据错误快速失败。产品选错文件/存储转录用scribe直播会议媒体用rtms。浏览器麦克风第 1 个分片正常、后续分片为空MediaRecorder.start(timeslice)长会话的后续 blob 可能是缺少容器头的部分 WebM/Opus 簇。首选修复按分片轮转录音器——启动录音器 → 记录一个分片窗口 → 停止 → 上传该 blob → 为下一分片重新启动新录音器。这是文件容器边界问题不是 Scribe 语言模型问题。5 分钟预检 Runbook 与快速决策树RUNBOOK.md 提供了深度调试前的预检清单与决策树浓缩如下预检七步确认产品文件/存储转录留在scribe直播媒体用rtms需要先入会录音的 bot 链路先走 Meeting SDK Linux。确认凭据Build-platform issuer 凭据对存在JWT 用HS256且过期不超过一小时secret 只留服务端拒绝${ZOOM_API_KEY}这类占位符。确认模式fast mode单短文件即时 JSON/ batch mode多文件/长录音/归档/ 麦克风伪流式短分片异步包装器。托管浏览器 UI 下 fast mode 应包装为「一次上传 → 后端返回202 请求 ID → 前端轮询」避免边缘超时竞态丢失成功转录。确认存储/Webhook 输入fast mode 文件 URL 或上传路径可解析batch 输入输出 URI 有效S3 模式 AWS 或预签名访问正确Webhook 地址为公网 HTTPS。确认后处理契约下游代码期待text_display、segments 还是逐词时间戳声道分离与 diarization 是否在发货前确定。快速探针本地 JWT 生成成功已知小文件POST /aiservices/scribe/transcribe成功浏览器上传经后端以multipart/form-data而非 JSONdata:URI 包装转发batch 提交返回201且带job_idWebhook 签名验证通过。决策树见下。快速决策树401/认证失败 → 凭据对错误或 JWT 过期fast mode 返回 schema 错误 → 请求体或 config 字段错误应用无日志就返回413→ 反向代理限制不是 Scribe前端504而后端日志稍后200→ 浏览器/边缘超时竞态按请求 ID 轮询而非判定失败麦克风功能需要真正的连续低延迟媒体 → 切换rtms不是scribe麦克风第 1 分片正常、后续为空 → 录音器/容器边界问题每个分片重启录音器batch 作业排队但永不完成 → 存储认证 / URI / Webhook 问题部分文件缺转录 → 先查/jobs/{jobId}/files再重提整个 batch版本漂移三张易变的面与维护触发点版本漂移文档 把「文档会变」本身当作必须管理的工程风险识别出三类漂移命名漂移API key/secret、SDK key/secret、ZOOM_API_KEY/SECRET并存统一按 Build-platform issuer/secret 对处理改生产代码前先到 Zoom 开发者 UI 核实标签。产品定位漂移Scribe 属于 AI Services但相关产品可能把用户引向 RTMS直播流、Meeting SDK Linux bot可见的会内捕获、AI Companion / REST APIZoom 生成摘要与转录。守住边界scribe 文件/存储转录rtms 直播媒体流摄入Meeting SDK Linux 参与者 bot 捕获/原始录音。工作流声明漂移部分博客材料把 Scribe 包装进「通话后摘要、工单充实、合规日志、可检索归档、客服 QA 管线、情绪/关键词下游分析」等语音洞察工作流。这些是合法的架构用例但不扩展当前文档化的端点面。实现规则scribe只负责生成转录情绪、分类、QA 评分、摘要全部放自己的下游管线不要仅凭博客措辞推断未文档化的实时或分析端点。API 表面漂移观察点关注 S3 之外的新存储提供方、config字段名变更、Webhook 签名头约定、响应 summary/file schema、语言与输出格式支持。重新审查触发点api-hub/ai-services/methods/endpoints.json变更、AI Services 文档再次改凭据命名、quickstart 样例改变 Webhook 或上传模式时需重新校对本文所引用的全部结论。延伸阅读scribe 技能入口与路由护栏认证与处理模式高等级场景Fast Mode Node 示例Batch 作业 Webhook 流水线示例API 参考环境变量样例验证版本漂移常见漂移与故障5 分钟预检 Runbook相邻技能rtms直播流、rest-apiREST 清单、webhooks签名加固【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 knowledge-work-plugins 中的 Zoom AI Services Scribe 转录实战指南：JWT 认证、Fast/Batch 双模式与浏览器麦克风伪流式架构
knowledge-work-plugins 中的 Zoom AI Services Scribe 转录实战指南JWT 认证、Fast/Batch 双模式与浏览器麦克风伪流式架构【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins本篇技术指南以开源仓库 knowledge-work-plugins 中 scribe 技能 及其配套子文档为核心完整讲解 Zoom AI Services Scribe 文件/存储转录服务的落地方法从 Build-platform JWT 签发、Fast Mode 同步转录与 Batch 异步批处理两条主链路到浏览器麦克风伪流式方案、Webhook 驱动的状态通知以及围绕版本漂移的排障与预检 Runbook。读完本文你将能独立搭建一条可运行的上传转录代理、批量 S3 转录与 Webhook 回写流水线并掌握 9 类高频故障的定位方法。Scribe 是什么文件/存储转录服务的定位与路由护栏Scribe 是 Zoom AI Services 家族中面向已上传或已存储媒体的转录服务核心能力是把音频/视频文件转成带时间戳、声道与说话人信息的文本。它与 Zoom 的实时媒体流服务 RTMS 边界清晰Scribe 处理「文件」RTMS 处理「直播流」。在 scribe 技能入口 中定义了四条路由护栏用于避免产品选错用户诉求路由目标上传或存储的媒体需要转成文本先路由到scribe需要实时会议媒体非文件上传/批处理转 rtms 技能需要 Zoom REST API 的 AI Services 路径清单串联 rest-api 技能需要 Webhook 签名模式或通用 HMAC 接收加固可选串联 webhooks 技能Scribe 覆盖的能力面包括同步单文件转录POST /aiservices/scribe/transcribe异步批量作业/aiservices/scribe/jobs*基于重复短文件上传的浏览器麦克风伪流式转录由 Webhook 驱动的批量状态更新Build-platform JWT 签发与凭据处理认证模型Build-platform JWT 与凭据命名漂移HS256 JWT 结构Scribe 使用Build-platform JWT Bearer Token认证而非 OAuth。JWT 的三要素算法HS256issueriss声明Build-platform 凭据标识符Scribe API 用它识别调用方过期时间exp保持在一小时或更短认证与处理模式文档 给出了 Node.js 侧的最小签发实现基于jsrsasign的KJURimport { KJUR } from jsrsasign; export function generateJWT(apiKey, apiSecret) { const iat Math.round(Date.now() / 1000) - 30; const exp iat 60 * 60; return KJUR.jws.JWS.sign( HS256, JSON.stringify({ alg: HS256, typ: JWT }), JSON.stringify({ iss: apiKey, iat, exp }), apiSecret, ); }注意iat回拨了 30 秒这是为时钟偏差留的缓冲exp设为iat 3600一小时。凭据命名漂移API Key 还是 SDK KeyZoom 官方文档在不同页面使用了不一致的命名AI Services 认证页API key/API secretBuild-platform 凭据页SDK key/SDK secretQuickstart 示例代码ZOOM_API_KEY/ZOOM_API_SECRET版本漂移文档 明确指出实现时统一把它们当作 Build-platform 的 JWT issuer/secret 对但在上线前务必到当前门户 UI 核实确切的字段标签。环境变量约定环境变量文档 给出了完整的配置面JWT 认证必填变量必填说明ZOOM_API_KEY是Build-platform issuer key用于 JWTiss声明ZOOM_API_SECRET是HS256 签名的 Build-platform secret通用应用变量变量必填说明PORT否本地服务端口LANGUAGE否默认语言代码如en-USBatch / S3 变量变量必填batch 场景说明S3_INPUT_URI通常输入前缀或文件 URIS3_OUTPUT_URI通常输出转录目的地AWS_ACCESS_KEY_ID未使用预签名访问时需要AWS 凭据AWS_SECRET_ACCESS_KEY未使用预签名访问时需要AWS 凭据AWS_SESSION_TOKEN常需要临时凭据令牌Webhook 变量变量必填说明WEBHOOK_URL可选接收批量通知的公网 HTTPS 回调WEBHOOK_SECRET可选但推荐校验 Zoom 回调签名的 HMAC secret关键坑不要把${ZOOM_API_KEY}这类 shell 占位符当作有效配置值。占位符会让健康检查「看起来已配置」但每次真实调用都会失败——这是文档与 Runbook 反复强调的失败模式。处理模式Fast Mode 与 Batch Mode 的选择认证与处理模式文档 对两种模式做了精确定位模式适用场景传输方式结果时机Fast mode单个短文件、交互式 UXPOST /transcribe立即返回同步 JSONBatch mode归档、长媒体、大量文件POST /jobs后查状态/等 Webhook异步选择 Fast mode 的条件用户只上传一个文件延迟比吞吐量更重要文件大小与时长可控在做基于短麦克风分片的浏览器伪流式选择 Batch mode 的条件需要处理大量文件转录结果可以稍后到达存储中心化工作流比直传更契合端点清单与请求/响应形状端点总览API 参考文档 基于 AI Services OpenAPI 清单api-hub/ai-services/methods/endpoints.json基础 URL 为https://api.zoom.us/v2MethodEndpoint说明Operation IDPOST/aiservices/scribe/transcribeScribe 同步转录createFastAsrPOST/aiservices/scribe/jobs提交批量 Scribe 作业submitBatchAsrGET/aiservices/scribe/jobs列出批量作业listBatchJobsGET/aiservices/scribe/jobs/{jobId}查询批量作业状态getBatchJobStatusDELETE/aiservices/scribe/jobs/{jobId}取消排队/处理中的作业cancelBatchJobGET/aiservices/scribe/jobs/{jobId}/files查看每个文件的转录结果listBatchJobFilesFast Mode 请求形状必填顶层字段file、config常见 config 字段认证与处理模式文档字段作用language语言代码如en-USword_time_offsets是否输出逐词时间偏移channel_separation是否按声道分离立体声通话录音timestamps时间戳output_format输出格式profanity_filter粗话过滤diarization说话人分离/区分响应关键键request_id、duration_sec、model、resultBatch Mode 请求形状必填顶层字段input、output、configinput 子字段modeSINGLE/PREFIX/MANIFESTsource当前 OpenAPI 中为S3uri/manifestfilters.include_globs、filters.exclude_globs均最多 10 项auth.aws.access_key_id/secret_access_key/session_tokenoutput 子字段destination、urilayoutSINGLE/PREFIX/ADJACENTauth.aws.*config 子字段language、word_time_offsets、channel_separation、diarization、profanity_filter、output_format、segmentation_mode可选字段reference_id、notifications.webhook_url、notifications.secret提交响应键job_id、state、submitted_at查询与状态端点GET /jobs查询参数state、page_size、next_page_token响应键jobs、next_page_tokenGET /jobs/{jobId}响应键job_id、state、submitted_at、summaryGET /jobs/{jobId}/files查询参数page_size、next_page_token响应键files、next_page_token当前限制与约束来自源文档Batch manifest 上限1000 个文件 URIinclude_globs最多10项exclude_globs最多10项文档标注的媒体格式WAV、MP3、M4A、MP4Fast mode 正式上限100 MB文件、2 小时时长OpenAPI 描述中批量作业的速率限制标签为LIGHT实战一Fast Mode 同步转录Node/Express 代理Fast Mode Node 示例 提供了一个可直接复用的最小后端代理。核心思路前端上传文件 → 后端签 JWT → 转发 multipart 到 Zoom → 回传转录 JSON。import express from express; import multer from multer; import { KJUR } from jsrsasign; const app express(); const upload multer({ storage: multer.memoryStorage() }); app.use(express.json()); function generateJWT() { const iat Math.round(Date.now() / 1000) - 30; const exp iat 60 * 60; return KJUR.jws.JWS.sign( HS256, JSON.stringify({ alg: HS256, typ: JWT }), JSON.stringify({ iss: process.env.ZOOM_API_KEY, iat, exp }), process.env.ZOOM_API_SECRET, ); } app.post(/transcribe, upload.single(file), async (req, res) { const token generateJWT(); const config { language: req.body.language || en-US, word_time_offsets: true, channel_separation: false, }; let response; if (req.file) { const form new FormData(); form.append(file, new Blob([new Uint8Array(req.file.buffer)]), req.file.originalname); form.append(config, JSON.stringify(config)); response await fetch(https://api.zoom.us/v2/aiservices/scribe/transcribe, { method: POST, headers: { Authorization: Bearer ${token} }, body: form, }); } else { response await fetch(https://api.zoom.us/v2/aiservices/scribe/transcribe, { method: POST, headers: { Authorization: Bearer ${token}, Content-Type: application/json, }, body: JSON.stringify({ file: req.body.file, config, }), }); } const text await response.text(); res.status(response.status).type(application/json).send(text); });该示例同时演示了 fast mode 的两种合法提交形态务必按服务边界选一种清晰的模型形态提交方式适用场景调用方上传文件到你的后端后端以multipart/form-data转发FormData携带fileconfig字符串浏览器/客户端直传调用方已有 URL 可访问的媒体后端以 JSON body 提交file字段放 URL服务端已存文件样例验证文档 补充了关键实现细节multer的 memory storage 对小型 fast mode 演示足够官方 quickstart 也证明「即使文档展示的是 JSON 示例fast mode 同样可以在你的服务器上以 multipart 上传处理方式代理」。实战二Batch 作业 Webhook 流水线端到端流程Batch 作业 Webhook 流水线示例 给出的链路为submit batch job - receive job_id - poll /jobs or wait for webhook - inspect /jobs/{jobId}/files - ingest transcript outputs提交示例curlcurl -X POST https://api.zoom.us/v2/aiservices/scribe/jobs -H Authorization: Bearer $TOKEN -H Content-Type: application/json -d { input: { mode: PREFIX, source: S3, uri: s3://example-bucket/audio/, auth: { aws: { access_key_id: ..., secret_access_key: ..., session_token: ... } } }, output: { destination: S3, uri: s3://example-bucket/transcripts/, layout: PREFIX, auth: { aws: { access_key_id: ..., secret_access_key: ..., session_token: ... } } }, config: { language: en-US, word_time_offsets: true, channel_separation: true }, notifications: { webhook_url: https://example.com/webhooks/scribe, secret: replace-me } }要点input.modePREFIX表示处理uri前缀下的全部匹配文件output.layoutPREFIX表示转录结果按源前缀镜像落盘AWS 凭据直接注入请求载荷——样例验证文档 指出这是 quickstart 的常规做法但生产流水线更建议使用预签名 URL 或短时 STS 临时凭据不要把长期 AK/SK 写进请求体。Webhook 签名验证Zoom 回调用的是x-zm-signaturex-zm-request-timestamp头HMAC-SHA256 计算后带sha256前缀。验证实现import crypto from crypto; function verifyZoomWebhook(rawBody, timestamp, signature, secret) { const message v0:${timestamp}:${rawBody}; const expected sha256${crypto.createHmac(sha256, secret).update(message).digest(hex)}; return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected)); }验证失败时按顺序排查raw body 是否在 JSON 解析前捕获、时间戳头是否纳入签名串、共享 secret 是否与作业的notifications.secret一致。浏览器麦克风伪流式模式Scribe 不暴露文档化的实时流 API因此浏览器麦克风体验必须建模为重复的短文件上传而不是一条长连接流。推荐的模式用MediaRecorder捕获浏览器麦克风音频按短分片 flush 到你的后端每个分片通过异步 fast mode 包装器提交按请求 ID 轮询完成状态按顺序拼接各分片转录结果推荐起始节奏分片大小5 秒可接受范围5-10 秒同时在途分片请求2-3个该模式的适用边界认证与处理模式文档 的护栏它本质上是「基于文件上传的伪流式」它不是实时音频捕获的首选生产设计仅当轻量浏览器演示或粗略的增量转录可接受时使用需要稳定低延迟实时转录、更低开销、跨语句强连续性时应避免真正的直播媒体流、低延迟服务端摄入或会议中连续音频改用 rtms高等级应用场景场景文档 给出了六类落地场景覆盖了从交互式单文件到离线合规处理的全谱系场景 1按需上传转录Fast mode浏览器上传 → 后端签发 Build JWT → 调用POST /aiservices/scribe/transcribe→ 返回转录 JSON。下游用途通话后摘要、工单充实、可检索片段库、内部审阅/交接笔记。场景 2批量 S3 归档转录Batch mode构建带输入前缀与输出前缀的批量请求 → 提交POST /aiservices/scribe/jobs→ 通过 Webhook 或轮询跟踪状态 → 读/jobs/{jobId}/files获取逐文件成败 → 导入搜索、分析或存储。下游用途合规与审计日志、可检索的网络研讨会/播客归档、批量转录回填、QA 评分输入。场景 3Zoom 录音导出后重新转录技能链zoom-rest-api拉取/下载录音 scribe转录导出媒体。典型动机自建留存/搜索管线、需要不同于 Zoom 托管默认的转录设置、用自建摘要/打标流程增强录音。场景 4合规 / QA 处理Batch mode离线生成用于审计、QA 评分或归档搜索的转录。优先项审阅者需要精确摘录时word_time_offsetstrue立体声通话录音用channel_separationtrue大流量下用 Webhook 队列摄入而非同步轮询。场景 5客服语音到洞察流水线录音入库 →scribe转录 → 存储转录文本及说话人/时间元数据 → 下游自建情绪、关键词、升级、QA 逻辑。护栏Scribe 只做转录情绪分析、关键词检测、评分全部放到转录生成后的下游服务。场景 6浏览器麦克风增量转录浏览器MediaRecorder捕获 → 每5 秒flush 一个分片 → 后端把每个分片当作普通 fast mode 上传经异步包装器提交 → 前端按请求 ID 轮询并按序拼接。护栏这是重复文件上传的伪流式最适合轻量演示或受限兜底真正的实时转录产品优先走rtms。故障排查与 5 分钟预检 Runbook九类高频故障速查常见漂移与故障文档 系统梳理了 9 类问题凭据看似正确但认证失败核对iss值、exp窗口、门户当前凭据标签确认不是把非 Build 应用凭据混用。若 API 返回{code:124,message:Invalid Access token}这是真实的上游认证失败而非传输问题。Fast mode 请求形状不匹配上传文件与 URL 文件是两条独立请求路径不要强行用单一 JSON 形态承载。症状是浏览器请求长时间挂起、后端最终超时或空响应。413 Request Entity Too Large通常是反向代理在请求到达应用前就拒绝了上传。nginx 前置时需把client_max_body_size抬到不低于服务端上传上限。504 Gateway time-out请求已到后端但同步处理超过边缘/代理路径时长。部署观测显示约 17.2 MB MP4 约 26s 完成约 38.6 MB 约 26-37s约 59.2 MB 约 32-34s后端但部分约 59.2 MB 浏览器请求先以504超时而后端日志显示200。前端 504 后端 200 浏览器/边缘超时竞态不是转录失败。建议为请求级日志记录文件名、大小、mime、上游耗时、响应载荷大小与顶层键托管 UI 用异步请求/轮询包装器若 nginx 访问日志出现499而应用日志稍后显示zoom_request_finished status: 200说明转录已成功、只是浏览器侧请求路径丢失。批量作业被接受但输出永不出现检查 S3 URI/认证不匹配、STS 凭据过期、输出 layout/URI 不匹配、依赖回调时 Webhook 端点不可达核对/jobs/{jobId}摘要与/jobs/{jobId}/files及云存储权限。Webhook 验证失败确认 raw body 捕获先于 JSON 解析、时间戳头纳入签名串、共享 secret 与作业通知配置一致。健康检查说凭据存在但 API 调用仍失败环境文件里多半是${ZOOM_API_KEY}这类字面占位符。只把真实值视为已配置并在调用 Zoom 前以明确的凭据错误快速失败。产品选错文件/存储转录用scribe直播会议媒体用rtms。浏览器麦克风第 1 个分片正常、后续分片为空MediaRecorder.start(timeslice)长会话的后续 blob 可能是缺少容器头的部分 WebM/Opus 簇。首选修复按分片轮转录音器——启动录音器 → 记录一个分片窗口 → 停止 → 上传该 blob → 为下一分片重新启动新录音器。这是文件容器边界问题不是 Scribe 语言模型问题。5 分钟预检 Runbook 与快速决策树RUNBOOK.md 提供了深度调试前的预检清单与决策树浓缩如下预检七步确认产品文件/存储转录留在scribe直播媒体用rtms需要先入会录音的 bot 链路先走 Meeting SDK Linux。确认凭据Build-platform issuer 凭据对存在JWT 用HS256且过期不超过一小时secret 只留服务端拒绝${ZOOM_API_KEY}这类占位符。确认模式fast mode单短文件即时 JSON/ batch mode多文件/长录音/归档/ 麦克风伪流式短分片异步包装器。托管浏览器 UI 下 fast mode 应包装为「一次上传 → 后端返回202 请求 ID → 前端轮询」避免边缘超时竞态丢失成功转录。确认存储/Webhook 输入fast mode 文件 URL 或上传路径可解析batch 输入输出 URI 有效S3 模式 AWS 或预签名访问正确Webhook 地址为公网 HTTPS。确认后处理契约下游代码期待text_display、segments 还是逐词时间戳声道分离与 diarization 是否在发货前确定。快速探针本地 JWT 生成成功已知小文件POST /aiservices/scribe/transcribe成功浏览器上传经后端以multipart/form-data而非 JSONdata:URI 包装转发batch 提交返回201且带job_idWebhook 签名验证通过。决策树见下。快速决策树401/认证失败 → 凭据对错误或 JWT 过期fast mode 返回 schema 错误 → 请求体或 config 字段错误应用无日志就返回413→ 反向代理限制不是 Scribe前端504而后端日志稍后200→ 浏览器/边缘超时竞态按请求 ID 轮询而非判定失败麦克风功能需要真正的连续低延迟媒体 → 切换rtms不是scribe麦克风第 1 分片正常、后续为空 → 录音器/容器边界问题每个分片重启录音器batch 作业排队但永不完成 → 存储认证 / URI / Webhook 问题部分文件缺转录 → 先查/jobs/{jobId}/files再重提整个 batch版本漂移三张易变的面与维护触发点版本漂移文档 把「文档会变」本身当作必须管理的工程风险识别出三类漂移命名漂移API key/secret、SDK key/secret、ZOOM_API_KEY/SECRET并存统一按 Build-platform issuer/secret 对处理改生产代码前先到 Zoom 开发者 UI 核实标签。产品定位漂移Scribe 属于 AI Services但相关产品可能把用户引向 RTMS直播流、Meeting SDK Linux bot可见的会内捕获、AI Companion / REST APIZoom 生成摘要与转录。守住边界scribe 文件/存储转录rtms 直播媒体流摄入Meeting SDK Linux 参与者 bot 捕获/原始录音。工作流声明漂移部分博客材料把 Scribe 包装进「通话后摘要、工单充实、合规日志、可检索归档、客服 QA 管线、情绪/关键词下游分析」等语音洞察工作流。这些是合法的架构用例但不扩展当前文档化的端点面。实现规则scribe只负责生成转录情绪、分类、QA 评分、摘要全部放自己的下游管线不要仅凭博客措辞推断未文档化的实时或分析端点。API 表面漂移观察点关注 S3 之外的新存储提供方、config字段名变更、Webhook 签名头约定、响应 summary/file schema、语言与输出格式支持。重新审查触发点api-hub/ai-services/methods/endpoints.json变更、AI Services 文档再次改凭据命名、quickstart 样例改变 Webhook 或上传模式时需重新校对本文所引用的全部结论。延伸阅读scribe 技能入口与路由护栏认证与处理模式高等级场景Fast Mode Node 示例Batch 作业 Webhook 流水线示例API 参考环境变量样例验证版本漂移常见漂移与故障5 分钟预检 Runbook相邻技能rtms直播流、rest-apiREST 清单、webhooks签名加固【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考