scribe

Zoom AI Services Scribe

Zoom AI Services Scribe 的背景参考，涵盖：

• 同步单文件转写（POST /aiservices/scribe/transcribe）
• 异步批量任务（/aiservices/scribe/jobs*）
• 通过重复上传短文件实现的浏览器麦克风伪流式处理
• Webhook 驱动的批量任务状态更新
• Build 平台 JWT 生成与凭证处理

官方文档：

• https://developers.zoom.us/docs/ai-services/
• https://developers.zoom.us/docs/ai-services/scribe/
• https://developers.zoom.us/docs/api/ai-services/
• https://developers.zoom.us/api-hub/ai-services/methods/endpoints.json
• 快速入门示例：https://github.com/zoom/scribe-quickstart/

路由准则

• 如果用户需要将已上传或已存储的媒体转写为文本，请优先路由至此。
• 如果用户需要处理实时会议媒体，且不涉及基于文件上传或批量任务，请路由至 ../rtms/SKILL.md。
• 如果用户需要 AI Services 路径的 Zoom REST API 清单，请串联 ../rest-api/SKILL.md。
• 如果用户需要 Webhook 签名模式或通用 HMAC 接收端加固，可选择串联 ../webhooks/SKILL.md。

快速链接

1. concepts/auth-and-processing-modes.md
2. scenarios/high-level-scenarios.md
3. examples/fast-mode-node.md
4. examples/batch-webhook-pipeline.md
5. references/api-reference.md
6. references/environment-variables.md
7. references/samples-validation.md
8. references/versioning-and-drift.md
9. troubleshooting/common-drift-and-breaks.md
10. RUNBOOK.md

核心工作流

1. 获取 Build 平台凭证并生成 HS256 JWT。
2. 单个短文件选择快速模式，已存档文件或大批量文件选择批量模式。
3. 提交转写请求。
4. 对于批量任务，轮询任务/文件状态，或接收 Webhook 通知。
5. 持久化并后处理转写 JSON。

托管快速模式准则

• 快速模式的正式 API 限制为 100 MB 和 2 小时，但托管的浏览器流程在上游响应返回之前仍可能超时。
• 当前已部署示例的观测结果：
  • 约 17.2 MB 的 MP4 在约 26s 内完成
  • 约 38.6 MB 的 MP4 在约 26-37s 内完成
  • 约 59.2 MB 的 MP4 在后端约 32-34s 内完成
  • 部分约 59.2 MB 的浏览器请求在前端显示 504，而后端日志随后显示 200
• 应将前端 504 加后端 200 视为浏览器/边缘超时竞争，而非自动判定的转写失败。
• 对于托管 UI，快速模式建议采用异步请求/轮询封装，而不是让浏览器一直等待完整的上游响应。
• 对于更大或较难预测的媒体，即使文件仍在快速模式的正式大小限制之内，也建议优先使用批量模式。

浏览器麦克风模式

• scribe 没有公开文档化的实时流式 API 接口。
• 如果你想要浏览器麦克风体验，请使用伪流式方案：
  1. 以短片段形式采集麦克风音频
  2. 通过异步快速模式封装上传每个片段
  3. 轮询直至完成
  4. 按顺序追加各片段的转录文本
• 推荐的起始节奏：
  • 片段大小：5 seconds
  • 可接受范围：5-10 seconds
  • 同时进行中的片段请求数：2-3
• 这是一种用于增量转录文本更新的实用 UI 模式，并不能替代 rtms。
• 请将其视为备用演示模式，而非首选的生产架构。
• 它会带来重复上传的开销、片段边界漂移、浏览器编解码器/容器的差异性，以及转录文本拼接的复杂度。
• 如果用户需要真正的实时流媒体接入、低延迟的连续媒体或服务端推送的媒体传输，请改为转至 ../rtms/SKILL.md。

端点概览

模式	方法	路径	用途
快速	POST	/aiservices/scribe/transcribe	对单个文件进行同步转录
批量	POST	/aiservices/scribe/jobs	提交异步批处理任务
批量	GET	/aiservices/scribe/jobs	列出任务
批量	GET	/aiservices/scribe/jobs/{jobId}	查看任务摘要/状态
批量	DELETE	/aiservices/scribe/jobs/{jobId}	取消排队中/处理中的任务
批量	GET	/aiservices/scribe/jobs/{jobId}/files	查看每个文件的结果

高层场景

• 用户上传一段录音后，按需转录片段。
• 对存储在 S3 中的通话归档进行批量转录。
• 由 Webhook 驱动的 ETL 流水线，将转录文本写入你的数据库/搜索索引。
• 将 Zoom 托管的录制导出到你自己的存储后，重新转录。
• 需要时间戳、声道分离和说话人提示的离线合规或质检工作流。

串联

• 已存储的 Zoom 录制 -> ../rest-api/SKILL.md + scribe
• Webhook 验证加固 -> ../webhooks/SKILL.md
• 实时直播转录/媒体 -> ../rtms/SKILL.md
• 跨产品路由 -> ../general/SKILL.md

运维

• RUNBOOK.md - 5 分钟预检和调试清单。