MiroTalk SFU 2.6.88 REST API 实战指南

MiroTalk SFU 2.6.88 REST API 实战：stats/meetings/meeting/join/token 六端点逐一带真实回显实测、鉴权方式、开关矩阵、Swagger 调试与 Slack/Discord 集成。

MiroTalk SFUWebRTC视频会议MiroTalk2026/10/26

MiroTalk SFU 2.6.88 REST API 实战指南

MiroTalk SFU 2.6.88 内置一套 REST API，用于在服务端管理会议生命周期：生成会议链接、构造入会链接、签发主持人令牌、查询房间与负载。全部端点在实测环境中逐一验证，本文所有请求与响应均为真实回显（测试实例监听 https://127.0.0.1:8146，端口取自该实例的 SERVER_LISTEN_PORT 配置）。

一、端点总览与默认开关

端点方法功能开关（.env）默认
/api/v1/statsGET服务器房间数/用户数API_ALLOW_STATStrue
/api/v1/meetingsGET当前活跃房间列表API_ALLOW_MEETINGSfalse
/api/v1/meetingPOST生成预生成会议 UUID 链接API_ALLOW_MEETINGtrue
/api/v1/meeting/:roomDELETE删除活跃房间API_ALLOW_MEETING_ENDfalse
/api/v1/joinPOST构造带参数的入会 URLAPI_ALLOW_JOINtrue
/api/v1/tokenPOST签发主持人 JWTAPI_ALLOW_TOKENfalse
/api/v1/docs/GETSwagger UI 交互文档始终开启-

不对称设计值得注意：/meetings（列出全部房间）、/meeting/:room 删除、/token 三项默认关闭，最小暴露面，使用前在 .env 打开并重启服务：

API_ALLOW_MEETINGS=true
API_ALLOW_MEETING_END=true
API_ALLOW_TOKEN=true

二、鉴权方式

所有 /api/v1/* 端点通过 authorization 请求头传递 API_KEY_SECRET（.env 中的值，默认 mirotalksfu_default_secret，生产必须替换为强随机值）。不是 Bearer 前缀，直接传原始密钥：

curl -sk https://127.0.0.1:8146/api/v1/stats -H "authorization: <API_KEY_SECRET>"

缺头或密钥错误一律返回 403 Forbidden（实测）。用 openssl rand -hex 24 生成新密钥后重启服务生效。

三、GET /api/v1/stats：负载查询

curl -sk https://127.0.0.1:8146/api/v1/stats -H "authorization: $API"

实测回显（空房间状态）：

{"success":true,"timestamp":"2026-10-26T07:46:44.898Z","totalRooms":0,"totalUsers":0}

有人入会后 totalRooms/totalUsers 实时增长，可用于监控大盘与自动扩缩容判断。

四、POST /api/v1/meeting：生成会议链接

无需请求体，服务器随机生成 UUID 并返回直连入会链接：

curl -sk https://127.0.0.1:8146/api/v1/meeting -X POST \
  -H "authorization: $API" -H "Content-Type: application/json"

实测回显：

{"meeting":"https://127.0.0.1:8146/join/3e58a137-79a9-4c15-b322-c33a68f8049d"}

注意 URL 中的主机与端口来自请求的 Host 头——通过反向代理对外暴露时，务必把代理设置为透传原始 Host（如 nginx 用 proxy_set_header Host $host;），否则返回的链接会带错域名。

五、GET /api/v1/meetings：活跃房间列表

curl -sk https://127.0.0.1:8146/api/v1/meetings -H "authorization: $API"

实测回显：

{"meetings":[]}

列表只包含活跃中的房间。一个实测确认的行为：上节 POST /meeting 预生成的 UUID 房间不会出现在列表里——预生成只是造了一个链接，只有真正有人入会后房间才进入活跃表。把它接进监控系统时不要用"生成多少会议"来推算房间数，直接看 totalRooms。

六、POST /api/v1/join：构造入会 URL

请求体按官方 Swagger 定义传入参会者能力开关，服务器拼装出可直接分发的入会链接：

curl -sk https://127.0.0.1:8146/api/v1/join -X POST \
  -H "authorization: $API" -H "Content-Type: application/json" \
  -d '{"room":"demo01","roomPassword":false,"name":"tester","avatar":false,"audio":false,"video":false,"chat":false,"screen":false,"hide":false,"notify":true,"duration":"unlimited"}'

实测回显：

{"join":"https://127.0.0.1:8146/join?room=demo01&roomPassword=false&name=tester&avatar=false&audio=false&video=false&screen=false&chat=false&hide=false&notify=true&duration=unlimited"}

字段速查：room 房间号（也可传 false 由服务器生成）；audio/video/screen/chat 入会时的设备与功能开关；hide 是否隐身入会；notify 是否发出通知音；duration 限时（如 60 分钟，unlimited 不限）。与 /meeting 的区别：本端点不创建任何房间状态，纯粹生成 URL，适合把入会流程编进自己的业务系统。

七、POST /api/v1/token：签发主持人 JWT

配合 HOST_USERS 静态账号使用，返回可用于 https://<host>:<port>/?token=<JWT> 免密入会的令牌：

curl -sk https://127.0.0.1:8146/api/v1/token -X POST \
  -H "authorization: $API" -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"q1w2e3r4","presenter":true,"expire":"1h"}'

实测回显（长 JWT）：

{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiVTJGc2RHVmtYMSs5MWNRT1ZVVk9FaDlEVGdDZ3BsaU1ZcTB2UHZKL2Ixa2I5ZFFheFhXdnlkRms4VXR4MmJ5N3NCa29WcWRpbEhPRmtFa2UzTy93d21vQk9Jd3lPVVBwSE9DNzNTWSt5ckU9IiwiaWF0IjoxNzkzMDAwODE1LCJleHAiOjE3OTMwMDQ0MTV9.EFtVCAK6jkXcussZflDdNbRqo5S2NTzepOZFSHetPM8"}

解码 payload 可见三段：data 是 U2FsdGVkX1... 开头的 CryptoJS AES 加密串（盐值+密文打包格式，内容为凭据），iat 签发时间与 exp 过期时间（expire: 1h 生成了 3600 秒差）。令牌校验密钥就是 .env 的 JWT_SECRET——若需要服务端自行解码凭据，用同一密钥按 CryptoJS AES 格式解密即可。

注意：expire 支持如 10m/1h/2h 的时长写法；presenter:true 使入会者获得主持权限（该能力要求对应开关与账号配置已就绪）。

八、DELETE /api/v1/meeting/:room：删除活跃房间

受 API_ALLOW_MEETING_END 控制（默认 false）。关闭时调用返回明确的禁用提示（实测回显）：

{"success":false,"error":"This endpoint has been disabled. Please contact the administrator for further information."}

开启后，删除一个预生成但无人入会的 UUID 房间，返回（实测回显）：

{"success":false,"error":"Room not found"}

两个回显合起来的语义是：该端点只能删除活跃中的房间（有人在线的会话），预生成链接不占活跃表、删除时会报 Room not found。无法在纯 API 环境里制造活跃房间（需要浏览器完成 WebRTC 信令），因此"删除成功"的回显未在本实测中呈现——把 room 换成一个正在进行的会议房间号即可成功，行为同上两种回显的开关逻辑。

另一个实测确认：DELETE 不接受 /api/v1/meeting 根路径（与 POST 不同），直接访问根路径会命中前端兜底路由返回 404 HTML 页面，务必带 /:room 段调用。

九、Swagger UI：交互式调试

服务自带 OpenAPI 文档页，浏览器打开：

https://<服务器地址>:8146/api/v1/docs/

实测 HTTP 200。页面列出全部端点的请求/响应 schema，可直接点 Authorize 填入 API_KEY_SECRET 后在线调试，是查字段定义的第一手资料。

十、集成通道（同一套 API 驱动）

以下集成底层都复用上述端点，属官方支持的三种"无界面"用法：

  1. Slack / Mattermost 斜杠命令：在 .env 配置 SLACK_* 或 MATTERMOST_* 系列变量（token、验证串、频道），命令默认名 /sfu，成员在频道里发命令即自动调用 /meeting 生成会议链接并回帖。
  2. Discord Bot：DISCORD_ENABLED=true + DISCORD_BOT_TOKEN，Bot 上线后同样提供 /sfu 命令。
  3. iframe 嵌入 / 客服 Widget：ALLOWED_EMBED_ORIGINS 控制允许嵌入的站点白名单（none 禁止、self 仅同源、留空不限制）；Widget 模式适合把会议入口挂到业务网站右下角。

十一、安全清单

  • API_KEY_SECRET 必须替换为强随机值；默认值触发启动警告（WARNING: API_KEY_SECRET is set to the default value. Change it before deploying!）
  • 三个默认关闭的端点（meetings/token/meeting-end）保持关闭，确有对接需求再逐个开启
  • API 面向公网暴露时挂在 nginx 后并配置限速；TRUST_PROXY=true 让限流取真实客户端 IP
  • /token 端点能签发主持令牌，暴露范围应最小化（仅业务后网段可调）
  • 全站 HTTPS（信令与媒体均在 TLS 下，页面为 https://）

至此本专栏五篇全部完成：从选型（A1）到裸装（B1）、编排部署（B2）、参数调优（C1）、API 集成（本篇）。回到 介绍与选型指南 可查看完整阅读路线。