Live777 HTTP API

WHIP && WHEP

POST /whip/:streamId

Response: [201]

如果该流已有 WHIP 推流，新推流会顶掉旧推流（mediamtx 式覆盖）：旧会话以 replaced 原因关闭。将 strategy.override_publisher = false（全局或按流）可改回重复推流返回 [409] 的行为。cascade 拉流的发布者永远不会被顶掉，冲突时始终返回 [409]。

POST /whep/:streamId

Response: [201]

PATCH /session/:streamId/:sessionId

Response: [204]

DELETE /session/:streamId/:sessionId

Response: [204]

Stream

创建一个流

POST /api/streams/:streamId

streamId 需要唯一标识符

你可以使用此配置自动创建流

toml

[strategy]
# WHIP auto a stream
auto_create_whip = true
# WHEP auto a stream
auto_create_whep = true

你也可以按流覆盖 strategy 字段：

toml

[stream.restricted]
[stream.restricted.strategy]
auto_create_whip = false
auto_create_whep = false

Response: [204]

Get all Stream

GET /api/streams/

Response: [200]

id: String, streamId
createdAt: Int, timestamp
publish: Object(PubSub), about publisher
subscribe: Object(PubSub), about subscriber
(publish | subscribe).leaveAt: Int, timestamp
(publish | subscribe).sessions: Array, sessions
(publish | subscribe).sessions.[].id: String, sessionId
(publish | subscribe).sessions.[].createdAt: Int, timestamp
(publish | subscribe).sessions.[].state: String, RTCPeerConnection/connectionState
(publish | subscribe).sessions.[].cascade: Optional(Object(Cascade))
(publish | subscribe).sessions.[].cascade.sourceUrl: Optional(String(URL))
(publish | subscribe).sessions.[].cascade.targetUrl: Optional(String(URL))
(publish | subscribe).sessions.[].cascade.sessionUrl: String(URL)
(publish | subscribe).sessions.[].stats: Object(Stats)，该会话的媒体统计：推流会话为输入方向，订阅会话为输出方向
(publish | subscribe).sessions.[].stats.bytes: Int，累计字节数（RTP 线上大小：头部 + 扩展 + 负载）
(publish | subscribe).sessions.[].stats.packets: Int，累计包数
(publish | subscribe).sessions.[].stats.bitrate: Int，当前码率（比特/秒，每 2 秒采样一次）
stats: Object，流级统计：stats.publish 为输入（推流）合计，stats.subscribe 为全部订阅输出合计；结构同为 Stats，累计计数在重新推流和订阅者进出时保持单调递增
statsScope: String，stats 的范围；node 表示单个 liveion 节点，clusterNodeWork 表示 liveman 跨节点合并的节点工作量，级联链路会计入每个中继节点

例如:

json

[
  {
    "id": "push",
    "createdAt": 1719326206862,
    "publish": {
      "leaveAt": 0,
      "sessions": [
        {
          "id": "08c1f2a0a60b0deeb66ee572bd369f80",
          "createdAt": 1719326206947,
          "state": "connected"
        }
      ]
    },
    "subscribe": {
      "leaveAt": 1719326206862,
      "sessions": []
    }
  },
  {
    "id": "pull",
    "createdAt": 1719326203854,
    "publish": {
      "leaveAt": 0,
      "sessions": [
        {
          "id": "41b2c52da4fb1eed5a3bff9a9a200d80",
          "createdAt": 1719326205079,
          "state": "connected",
          "cascade": {
            "sourceUrl": "http://localhost:7777/whep/web-0",
            "sessionUrl": "http://localhost:7777/session/web-0/aabc02240abfc7f4800e8d9a6f087808"
          }
        }
      ]
    },
    "subscribe": {
      "leaveAt": 1719326203854,
      "sessions": []
    }
  },
  {
    "id": "web-0",
    "createdAt": 1719326195910,
    "publish": {
      "leaveAt": 0,
      "sessions": [
        {
          "id": "0dc47d8da8eb0a64fe40f461f47c2a36",
          "createdAt": 1719326196264,
          "state": "connected"
        }
      ]
    },
    "subscribe": {
      "leaveAt": 0,
      "sessions": [
        {
          "id": "aabc02240abfc7f4800e8d9a6f087808",
          "createdAt": 1719326204997,
          "state": "connected"
        },
        {
          "id": "dab1a9e88b2400cfd4bcfb4487588ef3",
          "createdAt": 1719326206798,
          "state": "connected",
          "cascade": {
            "targetUrl": "http://localhost:7777/whip/push",
            "sessionUrl": "http://localhost:7777/session/push/08c1f2a0a60b0deeb66ee572bd369f80"
          }
        },
        {
          "id": "685beee8650b761116b581a4a87ca9b9",
          "createdAt": 1719326228314,
          "state": "connected"
        }
      ]
    }
  }
]

销毁一个流

DELETE /api/streams/:streamId

Response: [204]

配置文件中声明的流（[stream.<name>]）是预注册的，不能通过 API 删除或重复创建：对这些流执行 DELETE 或重复的 POST 会返回 [409]。

流状态 SSE

GET /api/sse/streams

Server-Sent Events 端点，和管理接口使用同样的鉴权。

当流状态发生变化时，推送所有流的全量快照。每条 SSE 消息都是一个流对象的 JSON 数组：

json

[
  {
    "id": "streamId",
    "publish": { ... },
    "subscribe": { ... },
    "reforward": { ... }
  }
]

连接建立后会立即发送第一条消息，之后每次状态变更都会再次推送当前完整状态；2 秒的统计采样周期在快照有变化时也会推送，因此有媒体流量时码率实时刷新，流静默时码率归零。

级联

POST /api/cascade/:streamId

Request:

json

{
  "token": "",
  "sourceUrl": "",
  "targetUrl": "",
}

token: Option, auth header
sourceUrl: Option<WHEP url>. if has, use pull mode
targetUrl: Option<WHIP url>. if has, use push mode
sourceUrl and targetUrl at the same time can only one

媒体源

码率端点是只读的编码器遥测（仅限原生采集/编码源，见 livehal 指南）：该源码率当前的驱动方式。档位端点是控制面：用命名的源参数预设（采集几何和/或编码预算）重新配置源。

查询源码率状态

GET /api/sources/:streamId/bitrate

查询该流配置的媒体源码率当前的驱动方式。

Response: [200]

json

{
  "stream_id": "pi-cam",
  "mode": "adaptive",
  "bitrate": 2000000,
  "adaptive": true
}

mode: adaptive（AIMD 控制器驱动）或 fixed（按配置值或最近应用的档位运行）。
bitrate: 当前编码器码率；源处于 standby 时为配置值（非原生源为 null）。

该流没有媒体源时返回 [404]；GET 以外的方法返回 [405]。

查询源质量档位

GET /api/sources/:streamId/tier

查询该流媒体源配置的质量档位以及当前生效的档位。

Response: [200]

json

{
  "stream_id": "pi-cam",
  "active_tier": "low",
  "tiers": [
    { "name": "mid", "bitrate": 2000000 },
    { "name": "low", "bitrate": 600000, "width": 640, "height": 480, "fps": 15 }
  ]
}

active_tier: 最后一次通过本 API 应用的档位（null 表示配置的基础档）。
tiers: 每项携带 bitrate；阶梯档还携带 width/height/fps （见 livehal 指南）。

该流没有媒体源时返回 [404]。

应用源质量档位

POST /api/sources/:streamId/tier

把源切换到某个配置好的质量档位：

json

{ "tier": "low" }

Response: [200]

json

{ "stream_id": "pi-cam", "tier": "low", "bitrate": 600000, "rebuilt": true }

纯码率档原地调运行中的编码器（rebuilt: false）；携带 width/height/fps 的档位重建采集+编码管线（rebuilt: true）：订阅者保持连接，但会观察到短暂断帧和一次带内 SPS/PPS 变更。两种方式都不会挂起自适应控制器——档位的码率成为 AIMD 的新上限，AIMD 继续在档内跟随网络状况调节。

[400] tier 缺失或该流未定义此档位。
[404] 该流没有媒体源。
[409] 源未在运行，或管线重建失败（已回滚到之前的配置）。

录制

开始录制流

POST /api/record/:streamId

开始录制指定的流。流必须处于活跃状态（有发布者）才能开始录制。需要启用 recorder 特性。

请求体（可选）：

json

{
  "base_dir": "optional/path/prefix"
}

base_dir（可选）：覆盖默认的目录前缀。如果不设置，录制会使用 /:streamId/:record_id/（10 位 Unix 时间戳）作为目录；当单次录制时长达到 max_recording_seconds 时，系统会自动以新的时间戳目录继续录制。

响应: [200]

json

{
  "id": "camera01",
  "record_id": "1718200000",
  "record_dir": "camera01/1718200000",
  "mpd_path": "camera01/1718200000/manifest.mpd"
}

当输出路径末尾不是 10 位 Unix 时间戳（例如自定义 base_dir 未包含该段）时，record_id 会返回为空字符串。

录制状态

GET /api/record/:streamId

响应: [200]

json

{ "recording": true }

停止录制

DELETE /api/record/:streamId

停止指定流的录制。成功时返回 [200]，响应体为空。

参考： Recorder

Live777 HTTP API ​

WHIP && WHEP ​

Stream ​

创建一个流 ​

Get all Stream ​

销毁一个流 ​

流状态 SSE ​

​级联 ​

媒体源 ​

查询源码率状态 ​

查询源质量档位 ​

应用源质量档位 ​

录制 ​

开始录制流 ​

录制状态 ​

停止录制 ​

Live777 HTTP API

WHIP && WHEP

Stream

创建一个流

Get all Stream

销毁一个流

流状态 SSE

级联

媒体源

查询源码率状态

查询源质量档位

应用源质量档位

录制

开始录制流

录制状态

停止录制