Meeting BaaS 会议转录教程：API v2 入会、Webhook、文件转存与失败处理

本教程用 Meeting BaaS API v2 跑通一条最小可验收的会议转录链路：拿到会议授权与 API Key、发送机器人、接收完成事件、转存转录、处理失败。示例使用 Google Meet 测试会议；正式接 Zoom 前还需完成其授权流程。代码中的会议地址、密钥和 webhook 端点都要替换成自己的值。

先准备授权和测试环境

1. 建立 Meeting BaaS 账号并取得 API Key；不要把 Key 放进浏览器、客户端应用或文章仓库。
2. 创建仅供测试的 Google Meet 会议，事先告知并取得所有适用参与者的录制同意。让机器人显示清楚的名称，不要伪装成人类参会者。
3. 在控制台配置账户级 webhook，保存签名密钥；给服务端准备 HTTPS 接收地址和私有文件存储。
4. 先设预算上限。Pay as you go 的 0 美元是 API 平台月费；前 4 小时录制免费，后续录制按 token，转录还会增加 token。

第一步：创建即时机器人

服务端使用官方 v2 接口，最小可转录请求如下。示例会议链接仅作格式说明，不应直接发送到别人的会议。

curl -X POST "https://api.meetingbaas.com/v2/bots" \
  -H "Content-Type: application/json" \
  -H "x-meeting-baas-api-key: YOUR-API-KEY" \
  -d '{
    "meeting_url": "https://meet.google.com/abc-defg-hij",
    "bot_name": "会议记录机器人",
    "recording_mode": "speaker_view",
    "transcription_enabled": true,
    "transcription_config": {"provider": "gladia"}
  }'

返回的 data.bot_id 要与业务会议 ID 关联保存。生产环境不要打印完整响应到公共日志，也不要在客户端直接调用这个 API。需要定时入会时，官方另有 POST /v2/bots/scheduled 与 join_at 字段；不要误把 join_at 发到即时接口。

第二步：用 webhook 驱动状态

账户级 webhook 使用 Svix 发送事件。接收服务应从原始请求体和 svix-id、svix-timestamp、svix-signature 验证签名，再解析 JSON；具体校验代码遵照 Svix 官方库和 Meeting BaaS 文档。不要只检查请求来源 IP 或明文 bot_id。对于同一个 event_id 做幂等去重，返回 2xx 后交由队列异步处理，避免下载大文件占用 webhook 请求时间。

可先只处理三类事件：

• bot.status_change：更新等待室、入会和录制状态，供用户看到进度。
• bot.completed：记录完成，取回转录、音频和视频 URL，启动安全转存任务。
• bot.failed：记录错误码和人工可理解的提示；只对可恢复错误重试，避免同一会议反复派机器人。

Meeting BaaS 也提供每个机器人独立的 callback，但它和账户级 Svix webhook 的签名机制不同。本文采用账户级 webhook，不要把两种验证方式混用。官方会重试未收到 2xx 的 webhook，所以幂等是必需项。

第三步：转存与处理转录

bot.completed 的下载地址是预签名 URL，官方文档标注有效 4 小时。收到事件后尽快将文件下载到权限隔离的对象存储，记录校验和、bot_id、会议 ID、到期时间和删除日期。只向有权查看会议的用户暴露经过授权的自家下载接口，不要把上游预签名 URL 放到公开页面或分析日志。

转录数据可包含时间戳与说话人信息。先把转录句段和参会者映射保存，再运行摘要模型；对说话人不确定、多人重叠或低置信度段落保留原文，不要让模型自行补写。业务动作如更新 CRM、创建任务或发送外部消息，应由用户审阅并确认。文本总结之外的音视频文件，可按最短必要期限保留。

第四步：回查状态并处理失败

如果 webhook 暂时未到，可以用 GET /v2/bots/{bot_id}/status 轻量查询；完成后再用 GET /v2/bots/{bot_id} 拉取产物。官方推荐以 webhook 或 callback 为主，轮询仅作对账。对等待室超时、被主持人拒绝、无效会议链接和 token 不足分别处理：前几种需要用户或主持人动作，余额问题需要预算提示，不应无条件自动重试。

Zoom 场景要单独验收。Meeting BaaS 价格页提示自 2026 年 3 月 2 日起 Zoom 机器人必须授权，需创建 Zoom Marketplace 应用并配置 OBF 或 ZAK。仅替换会议 URL 并不足以保证接入成功。Teams 也要在目标组织租户中验证准入和录制策略。

上线验收表

• 在三种平台各跑至少 10 场，涵盖等待室、未准入、主持人提前结束、长会议和网络抖动，记录准时入会率、有效转录率及完成到可下载时延。
• 用伪造签名请求验证 webhook 必须拒绝；用重复 event_id 验证不会重复生成摘要。
• 在 4 小时产物 URL 到期前完成转存；模拟下载失败并确认队列重试和告警。
• 按录制 1 token/小时、Gladia 转录另加 0.25 token/小时及购买的 token 包，计算每成功小时成本；扩大并发前复核月费档位。
• 检查参会者告知、权限隔离、删除请求、保留期和审计记录。

资料：发送机器人、Webhook 与签名、获取数据、价格页。