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，启动安全转存任务。