HTTP API 概览

Monibuca V6 通过内置的共享 HTTP 服务器统一对外提供 API。所有插件的 HTTP 端点都注册在同一个服务器上，通过路由前缀区分。

服务地址

默认监听地址为 :8080，可通过配置修改：

http:
  listen: ":8080"
  cors: true

路由前缀分类

所有 API 按功能模块组织为不同的路由前缀：

核心 API

前缀	模块	说明
/api/	引擎核心	流管理、系统信息、插件管理
/config/	配置管理	配置读写、Schema 查询、热更新

协议 API

前缀	插件	说明
/rtmp/	RTMP	RTMP 连接管理
/rtsp/	RTSP	RTSP 会话管理
/flv/	HTTP-FLV	FLV 拉流接口
/hls/	HLS	HLS 播放列表与切片
/webrtc/	WebRTC	WHIP/WHEP 信令接口
/srt/	SRT	SRT 连接管理
/webtransport/	WebTransport	WebTransport 会话
/gb28181/	GB28181	设备管理与控制

工具 API

前缀	插件	说明
/mp4/	MP4 录制	录制控制与点播
/snap/	截图服务	截图与 MJPEG
/transcode/api/	音频转码	转码任务管理
/cluster/	集群	集群状态与节点管理

房间 API

前缀	服务/插件	说明
/room/	Room 服务	房间管理
/room_report/	Room 上报	房间统计数据
/live/	Live 插件	直播间管理
/meeting/api/	Meeting 插件	会议室 REST（房间、预订、模板等）

Meeting REST

以下为会议室（Meeting）插件的 HTTP 接口说明，与仓库根目录 docs/http-api.md 中「14.2 Meeting」一节保持一致；修改路由时请同时更新两处，避免站内页与源码旁文档漂移。

与其它插件相同，Meeting 的 REST 挂在 {plugin}/api 下，即 /meeting/api；引擎注册前缀 meeting/api 后，处理器收到的子路径为 /rooms、/reservations 等（与 gb28181/api、/users/api 等模式相同）。

路由前缀

前缀	用途	处理器
/meeting/api	会议室 REST	MeetingApiHandler

完整路径（客户端请求）

方法	路径	说明
GET	/meeting/api/rooms	会议室列表
POST	/meeting/api/rooms	创建会议室（JSON：room_id）
GET	/meeting/api/rooms/{room_id}	获取会议室摘要；兼容 GET /meeting/api/room/{room_id}
DELETE	/meeting/api/rooms/{room_id}	删除会议室
GET	/meeting/api/rooms/{room_id}/users	会议室用户列表
POST	/meeting/api/rooms/{room_id}/lock	锁定会议室
POST	/meeting/api/rooms/{room_id}/unlock	解锁会议室
POST	/meeting/api/control/mute	禁言（JSON：room_id、user_id）
POST	/meeting/api/control/unmute	取消禁言
POST	/meeting/api/control/kick	踢出用户
GET	/meeting/api/stats	会议统计
GET	/meeting/api/features	已注册特性元数据
GET	/meeting/api/reservations	预订列表
POST	/meeting/api/reservations	创建预订
GET	/meeting/api/templates	模板列表
POST	/meeting/api/templates	创建模板
PUT	/meeting/api/templates/{id}	更新模板
DELETE	/meeting/api/templates/{id}	删除模板
GET	/meeting/api/recordings	录制条目列表（持久化目录未接入时可能为空）
GET	/meeting/api/recordings/{id}/play	播放（未命中返回 404）
GET	/meeting/api/recordings/{id}/download	下载
DELETE	/meeting/api/recordings/{id}	删除录制记录

说明： 议程、转写、会中实时控制等仍以 WebSocket（/room/{room_id}?type=meeting）为主；勿使用已废弃的 /room/meeting/... 前缀书写 Meeting REST。概念与信令详见 会议室插件。

通用请求规范

请求格式

• Content-Type：application/json（POST/PUT 请求）
• 字符编码：UTF-8
• URL 编码：路径中的特殊字符使用标准 URL 编码

通用响应格式

大部分 API 返回统一的 JSON 结构：

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

字段	类型	说明
code	int	状态码，0 表示成功
message	string	状态描述
data	object	响应数据（可选）

HTTP 状态码

状态码	说明
200	请求成功
400	请求参数错误
401	未授权（需要认证）
403	禁止访问
404	资源不存在
500	服务器内部错误
501	功能未实现
503	服务不可用

认证机制

Monibuca V6 支持通过 JWT（JSON Web Token）进行 API 认证。

启用认证

auth:
  enabled: true
  secret: "your-jwt-secret-key"
  expire: 86400              # Token 有效期（秒）
  exclude:                   # 免认证路径
    - "/api/login"
    - "/flv/"
    - "/hls/"

获取 Token

POST /api/login
Content-Type: application/json

{
  "username": "admin",
  "password": "password"
}

响应：

{
  "code": 0,
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

使用 Token

在后续请求的 Header 中携带 Token：

GET /api/streams
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

鉴权签名接口

用于生成 v5 兼容的流鉴权签名（secret + expire）：

GET /api/secret/{publish|subscribe}/{streamPath...}?expire=<hex>&plugin=<pluginName>

• type：publish 或 subscribe
• streamPath：流路径（可 URL 编码）
• expire：可选，16 进制 Unix 时间戳；不传默认当前时间 + 30 分钟
• plugin：可选，插件名；默认 global

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "type": "publish",
    "plugin": "rtmp",
    "streamPath": "live/test",
    "expire": "6610f4a0",
    "secret": "0123456789abcdef0123456789abcdef"
  }
}

CORS 支持

默认启用 CORS，允许跨域访问。可通过配置控制：

http:
  cors: true
  cors_origins:
    - "http://localhost:3000"
    - "https://your-domain.com"

API 文档导航

• Meeting REST — 会议室插件完整路径表（与 docs/http-api.md §14.2 对齐）
• 流管理 API — 流的列表、详情、控制
• 配置管理 API — 配置的读写与热更新
• GB28181 API — 国标设备管理与控制
• 高级：流鉴权 — 鉴权算法、自定义处理器与签名接口