Skip to content

MediaServer支持的HTTP API

Jump to bottom
xiongziliang edited this page Mar 17, 2026 · 92 revisions

下载postman配置文件(可以在线测试restful api)

postman配置文件

由于接口更新频繁，在观看本文档的同时，请大家再使用postman核对测试接口，同时本文档可能有些接口有遗漏，你也可以参考代码(查看api_regist相关)

API预览

MediaServer是ZLMediaKit的主进程，目前支持以下http api接口，这些接口全部支持GET/POST方式，

      "/index/api/addFFmpegSource",
      "/index/api/addStreamProxy",
      "/index/api/addStreamPusherProxy",
      "/index/api/addWebrtcRoomKeeper",
      "/index/api/broadcastMessage",
      "/index/api/closeRtpServer",
      "/index/api/close_stream",
      "/index/api/close_streams",
      "/index/api/connectRtpServer",
      "/index/api/delFFmpegSource",
      "/index/api/delStreamProxy",
      "/index/api/delStreamPusherProxy",
      "/index/api/delWebrtcRoomKeeper",
      "/index/api/delete_webrtc",
      "/index/api/deleteRecordDirectory",
      "/index/api/deleteSnapDirectory",
      "/index/api/downloadBin",
      "/index/api/downloadFile",
      "/index/api/getAllSession",
      "/index/api/getApiList",
      "/index/api/getMediaInfo",
      "/index/api/getMediaList",
      "/index/api/getMediaPlayerList",
      "/index/api/getMP4RecordFile",
      "/index/api/getProxyInfo",
      "/index/api/getProxyPusherInfo",
      "/index/api/getRtpInfo",
      "/index/api/getServerConfig",
      "/index/api/getSnap",
      "/index/api/getStatistic",
      "/index/api/getStreamUrl",
      "/index/api/getThreadsLoad",
      "/index/api/getWebrtcProxyPlayerInfo",
      "/index/api/getWorkThreadsLoad",
      "/index/api/isMediaOnline",
      "/index/api/isRecording",
      "/index/api/kick_session",
      "/index/api/kick_sessions",
      "/index/api/listFFmpegSource",
      "/index/api/listRtpSender",
      "/index/api/listRtpServer",
      "/index/api/listStreamProxy",
      "/index/api/listStreamPusherProxy",
      "/index/api/listWebrtcRoomKeepers",
      "/index/api/listWebrtcRooms",
      "/index/api/loadMP4File",
      "/index/api/login",
      "/index/api/logout",
      "/index/api/openRtpServer",
      "/index/api/openRtpServerMultiplex",
      "/index/api/pauseRtpCheck",
      "/index/api/restartServer",
      "/index/api/resumeRtpCheck",
      "/index/api/searchOnvifDevice",
      "/index/api/seekRecordStamp",
      "/index/api/setRecordSpeed",
      "/index/api/setServerConfig",
      "/index/api/stack/start",
      "/index/api/stack/stop",
      "/index/api/stack/reset",
      "/index/api/startRecord",
      "/index/api/startRecordTask",
      "/index/api/startSendRtp",
      "/index/api/startSendRtpPassive",
      "/index/api/startSendRtpTalk",
      "/index/api/stopRecord",
      "/index/api/stopSendRtp",
      "/index/api/updateRtpServerSSRC",
      "/index/api/version",
      "/index/api/webrtc",
      "/index/api/whip",
      "/index/api/whep"

其中POST方式，参数既可以使用urlencoded方式也可以使用json方式。 操作这些api一般需要提供secret参数以便鉴权，如果调用/index/api/login接口比并处于已cookie登录状态，则无需提供secret参数鉴权 如果操作ip是127.0.0.1，那么可以无需鉴权。

新版本已删除上条机制

API返回结果约定

  • HTTP层面统一返回200状态码，body统一为json。
  • body一般为以下样式：
{
    "code" : -1,
    "msg" : "失败提示"
}
  • code值代表执行结果，目前包含以下类型：
typedef enum {
    Exception = -400,//代码抛异常
    InvalidArgs = -300,//参数不合法
    SqlFailed = -200,//sql执行失败
    AuthFailed = -100,//鉴权失败
    OtherFailed = -1,//业务代码执行失败，
    Success = 0//执行成功
} ApiErr;

  • 如果执行成功，那么code == 0,并且一般无msg字段。

  • code == -1时代表业务代码执行不成功，更细的原因一般提供result字段，例如以下：

{
    "code" : -1, # 代表业务代码执行失败
    "msg" : "can not find the stream", # 失败提示
    "result" : -2 # 业务代码执行失败具体原因
}

  • 开发者一般只要关注code字段和msg字段，如果code != 0时，打印显示msg字段即可。

  • code == 0时代表完全成功，如果有数据返回，一般提供data字段返回数据。

API详解

0、/index/api/getApiList

  • 功能：获取API列表

  • 范例：http://127.0.0.1/index/api/getApiList

  • 参数：无

  • 响应：

    {
  "code": 0,
  "data": [
      "/index/",
      "/index/api/addFFmpegSource",
      "/index/api/addStreamProxy",
      "/index/api/addStreamPusherProxy",
      "/index/api/addWebrtcRoomKeeper",
      "/index/api/broadcastMessage",
      "/index/api/close_stream",
      "/index/api/close_streams",
      "/index/api/closeRtpServer",
      "/index/api/connectRtpServer",
      "/index/api/delete_webrtc",
      "/index/api/deleteRecordDirectory",
      "/index/api/deleteSnapDirectory",
      "/index/api/delFFmpegSource",
      "/index/api/delStreamProxy",
      "/index/api/delStreamPusherProxy",
      "/index/api/delWebrtcRoomKeeper",
      "/index/api/downloadBin",
      "/index/api/downloadFile",
      "/index/api/getAllSession",
      "/index/api/getApiList",
      "/index/api/getMediaInfo",
      "/index/api/getMediaList",
      "/index/api/getMediaPlayerList",
      "/index/api/getMP4RecordFile",
      "/index/api/getProxyInfo",
      "/index/api/getProxyPusherInfo",
      "/index/api/getRtpInfo",
      "/index/api/getServerConfig",
      "/index/api/getSnap",
      "/index/api/getStatistic",
      "/index/api/getStreamUrl",
      "/index/api/getThreadsLoad",
      "/index/api/getWebrtcProxyPlayerInfo",
      "/index/api/getWorkThreadsLoad",
      "/index/api/isMediaOnline",
      "/index/api/isRecording",
      "/index/api/kick_session",
      "/index/api/kick_sessions",
      "/index/api/listFFmpegSource",
      "/index/api/listRtpSender",
      "/index/api/listRtpServer",
      "/index/api/listStreamProxy",
      "/index/api/listStreamPusherProxy",
      "/index/api/listWebrtcRoomKeepers",
      "/index/api/listWebrtcRooms",
      "/index/api/loadMP4File",
      "/index/api/login",
      "/index/api/logout",
      "/index/api/openRtpServer",
      "/index/api/openRtpServerMultiplex",
      "/index/api/pauseRtpCheck",
      "/index/api/restartServer",
      "/index/api/resumeRtpCheck",
      "/index/api/searchOnvifDevice",
      "/index/api/seekRecordStamp",
      "/index/api/setRecordSpeed",
      "/index/api/setServerConfig",
      "/index/api/startRecord",
      "/index/api/startRecordTask",
      "/index/api/startSendRtp",
      "/index/api/startSendRtpPassive",
      "/index/api/startSendRtpTalk",
      "/index/api/stopRecord",
      "/index/api/stopSendRtp",
      "/index/api/updateRtpServerSSRC",
      "/index/api/version",
      "/index/api/webrtc",
      "/index/api/whep",
      "/index/api/whip"
  ]
}

1、/index/api/getThreadsLoad

  • 功能：获取各epoll(或select)线程负载以及延时

  • 范例：http://127.0.0.1/index/api/getThreadsLoad

  • 参数：无

  • 响应:

    {
   "code" : 0,
   "data" : [
      {
         "delay" : 0, # 该线程延时
         "load" : 0 # 该线程负载，0 ~ 100
      },
      {
         "delay" : 0,
         "load" : 0
      }
   ]
}

2、/index/api/getWorkThreadsLoad

  • 功能：获取各后台epoll(或select)线程负载以及延时

  • 范例：http://127.0.0.1/index/api/getWorkThreadsLoad

  • 参数：无

  • 响应:

    {
   "code" : 0,
   "data" : [
      {
         "delay" : 0, # 该线程延时
         "load" : 0 # 该线程负载，0 ~ 100
      },
      {
         "delay" : 0,
         "load" : 0
      }
   ]
}

3、/index/api/getServerConfig

  • 功能：获取服务器配置

  • 范例：http://127.0.0.1/index/api/getServerConfig

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)

  • 响应：

    {
   "code" : 0,
   "data" : [
      {
         "api.apiDebug" : "1",
         "api.secret" : "035c73f7-bb6b-4889-a715-d9eb2d1925cc",
         "ffmpeg.bin" : "/usr/local/bin/ffmpeg",
         "ffmpeg.cmd" : "%s -i %s -c:a aac -strict -2 -ar 44100 -ab 48k -c:v libx264 -f flv %s",
         "ffmpeg.log" : "/Users/xzl/git/ZLMediaKit/cmake-build-debug/bin/ffmpeg/ffmpeg.log",
         "general.enableVhost" : "1",
         "general.flowThreshold" : "1024",
         "general.maxStreamWaitMS" : "5000",
         "general.streamNoneReaderDelayMS" : "5000",
         "hls.fileBufSize" : "65536",
         "hls.filePath" : "/Users/xzl/git/ZLMediaKit/cmake-build-debug/bin/httpRoot",
         "hls.segDur" : "3",
         "hls.segNum" : "3",
         "hook.access_file_except_hls" : "1",
         "hook.admin_params" : "secret=035c73f7-bb6b-4889-a715-d9eb2d1925cc",
         "hook.enable" : "1",
         "hook.on_flow_report" : "https://127.0.0.1/index/hook/on_flow_report",
         "hook.on_http_access" : "https://127.0.0.1/index/hook/on_http_access",
         "hook.on_play" : "https://127.0.0.1/index/hook/on_play",
         "hook.on_publish" : "https://127.0.0.1/index/hook/on_publish",
         "hook.on_record_mp4" : "https://127.0.0.1/index/hook/on_record_mp4",
         "hook.on_rtsp_auth" : "https://127.0.0.1/index/hook/on_rtsp_auth",
         "hook.on_rtsp_realm" : "https://127.0.0.1/index/hook/on_rtsp_realm",
         "hook.on_shell_login" : "https://127.0.0.1/index/hook/on_shell_login",
         "hook.on_stream_changed" : "https://127.0.0.1/index/hook/on_stream_changed",
         "hook.on_stream_none_reader" : "https://127.0.0.1/index/hook/on_stream_none_reader",
         "hook.on_stream_not_found" : "https://127.0.0.1/index/hook/on_stream_not_found",
         "hook.timeoutSec" : "10",
         "http.charSet" : "utf-8",
         "http.keepAliveSecond" : "100",
         "http.maxReqCount" : "100",
         "http.maxReqSize" : "4096",
         "http.notFound" : "<html><head><title>404 Not Found</title></head><body bgcolor=\"white\"><center><h1>您访问的资源不存在！</h1></center><hr><center>ZLMediaKit-4.0</center></body></html>",
         "http.port" : "80",
         "http.rootPath" : "/Users/xzl/git/ZLMediaKit/cmake-build-debug/bin/httpRoot",
         "http.sendBufSize" : "65536",
         "http.sslport" : "443",
         "multicast.addrMax" : "239.255.255.255",
         "multicast.addrMin" : "239.0.0.0",
         "multicast.udpTTL" : "64",
         "record.appName" : "record",
         "record.filePath" : "/Users/xzl/git/ZLMediaKit/cmake-build-debug/bin/httpRoot",
         "record.fileSecond" : "3600",
         "record.sampleMS" : "100",
         "rtmp.handshakeSecond" : "15",
         "rtmp.keepAliveSecond" : "15",
         "rtmp.modifyStamp" : "1",
         "rtmp.port" : "1935",
         "rtp.audioMtuSize" : "600",
         "rtp.clearCount" : "10",
         "rtp.cycleMS" : "46800000",
         "rtp.maxRtpCount" : "50",
         "rtp.videoMtuSize" : "1400",
         "rtsp.authBasic" : "0",
         "rtsp.handshakeSecond" : "15",
         "rtsp.keepAliveSecond" : "15",
         "rtsp.port" : "554",
         "rtsp.sslport" : "322",
         "shell.maxReqSize" : "1024",
         "shell.port" : "9000"
      }
   ]
}

4、/index/api/setServerConfig

5、/index/api/restartServer

  • 功能：重启服务器,只有Daemon方式才能重启，否则是直接关闭！

  • 范例：http://127.0.0.1/index/api/restartServer

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)

  • 响应：

    {
   "code" : 0,
   "msg" : "服务器将在一秒后自动重启"
}

6、/index/api/getMediaList

  • 功能：获取流列表，可选筛选参数

  • 范例：http://127.0.0.1/index/api/getMediaList

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)
    schema N 筛选协议，例如 rtsp或rtmp
    vhost N 筛选虚拟主机，例如__defaultVhost__
    app N 筛选应用名，例如 live
    stream N 筛选流id，例如 test

  • 响应：

    {
  "code" : 0,
  "data" : [
  {
     "app" : "live",  # 应用名
     "readerCount" : 0, # 本协议观看人数
     "totalReaderCount" : 0, # 观看总人数，包括hls/rtsp/rtmp/http-flv/ws-flv
     "schema" : "rtsp", # 协议
     "stream" : "obs", # 流id
     "originSock": {  # 客户端和服务器网络信息，可能为null类型
            "identifier": "140241931428384",
            "local_ip": "127.0.0.1",
            "local_port": 1935,
            "peer_ip": "127.0.0.1",
            "peer_port": 50097
        },
     "originType": 1, # 产生源类型，包括 unknown = 0,rtmp_push=1,rtsp_push=2,rtp_push=3,pull=4,ffmpeg_pull=5,mp4_vod=6,device_chn=7
     "originTypeStr": "MediaOriginType::rtmp_push",
     "originUrl": "rtmp://127.0.0.1:1935/live/hks2", #产生源的url
     "createStamp": 1602205811, #GMT unix系统时间戳，单位秒
     "aliveSecond": 100, #存活时间，单位秒
     "bytesSpeed": 12345, #数据产生速度，单位byte/s
     "tracks" : [    # 音视频轨道
        {
           "channels" : 1, # 音频通道数
           "codec_id" : 2, # H264 = 0, H265 = 1, AAC = 2, G711A = 3, G711U = 4
           "codec_id_name" : "CodecAAC", # 编码类型名称 
           "codec_type" : 1, # Video = 0, Audio = 1
           "ready" : true, # 轨道是否准备就绪
           "frames" : 1119, #累计接收帧数
           "sample_bit" : 16, # 音频采样位数
           "sample_rate" : 8000 # 音频采样率
        },
        {
           "codec_id" : 0, # H264 = 0, H265 = 1, AAC = 2, G711A = 3, G711U = 4
           "codec_id_name" : "CodecH264", # 编码类型名称  
           "codec_type" : 0, # Video = 0, Audio = 1
           "fps" : 59,  # 视频fps
           "frames" : 1119, #累计接收帧数，不包含sei/aud/sps/pps等不能解码的帧
           "gop_interval_ms" : 1993, #gop间隔时间，单位毫秒
           "gop_size" : 60, #gop大小，单位帧数
           "key_frames" : 21, #累计接收关键帧数
           "height" : 720, # 视频高
           "ready" : true,  # 轨道是否准备就绪
           "width" : 1280 # 视频宽
        }
     ],
     "vhost" : "__defaultVhost__" # 虚拟主机名
   }
  ]
}

7、/index/api/close_stream(已过期，请使用close_streams接口替换)

  • 功能：关闭流(目前所有类型的流都支持关闭)

  • 范例：http://127.0.0.1/index/api/close_stream?schema=rtmp&vhost=__defaultVhost__&app=live&stream=0&force=1

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)
    schema Y 协议，例如 rtsp或rtmp
    vhost Y 虚拟主机，例如__defaultVhost__
    app Y 应用名，例如 live
    stream Y 流id，例如 test
    force N 是否强制关闭(有人在观看是否还关闭)

  • 响应：

    {
   "code" : 0,
   "result" : 0,# 0:成功，-1:关闭失败，-2:该流不存在
   "msg" : "success"
}

8、/index/api/close_streams

  • 功能：关闭流(目前所有类型的流都支持关闭)

  • 范例：http://127.0.0.1/index/api/close_streams?schema=rtmp&vhost=__defaultVhost__&app=live&stream=0&force=1

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)
    schema N 协议，例如 rtsp或rtmp
    vhost N 虚拟主机，例如__defaultVhost__
    app N 应用名，例如 live
    stream N 流id，例如 test
    force N 是否强制关闭(有人在观看是否还关闭)

  • 响应：

    {
   "code" : 0,
   "count_hit" : 1,  # 筛选命中的流个数
   "count_closed" : 1 # 被关闭的流个数，可能小于count_hit
}

9、/index/api/getAllSession

  • 功能：获取所有TcpSession列表(获取所有tcp客户端相关信息)

  • 范例：http://127.0.0.1/index/api/getAllSession

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)
    local_port N 筛选本机端口，例如筛选rtsp链接：554
    peer_ip N 筛选客户端ip

  • 响应：

    {
   "code" : 0,
   "data" : [
      {
         "id" : "140614477848784",
         "local_ip" : "127.0.0.1",
         "local_port" : 80,
         "peer_ip" : "127.0.0.1",
         "peer_port" : 51136,
         "typeid" : "16WebSocketSessionI11EchoSessionN8mediakit11HttpSessionEE"
      },
      {
         "id" : "140614443300192",
         "local_ip" : "127.0.0.1",
         "local_port" : 80,
         "peer_ip" : "127.0.0.1",
         "peer_port" : 51135,
         "typeid" : "16WebSocketSessionI11EchoSessionN8mediakit11HttpSessionEE"
      },
      {
         "id" : "140614440178720",  # 该tcp链接唯一id
         "local_ip" : "127.0.0.1",  # 本机网卡ip
         "local_port" : 1935, 			# 本机端口号	(这是个rtmp播放器或推流器)
         "peer_ip" : "127.0.0.1",   # 客户端ip 
         "peer_port" : 51130,				# 客户端端口号
         "typeid" : "N8mediakit11RtmpSessionE"  # 客户端TCPSession typeid
      }
   ]
}

10、/index/api/kick_session

  • 功能：断开tcp连接，比如说可以断开rtsp、rtmp播放器等

  • 范例：http://127.0.0.1/index/api/kick_session?id=140614440178720

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)
    Id Y 客户端唯一id，可以通过getAllSession接口获取

  • 响应：

    {
   "code" : 0,
   "msg" : "success"
}

11、/index/api/kick_sessions

  • 功能：断开tcp连接，比如说可以断开rtsp、rtmp播放器等

  • 范例：http://127.0.0.1/index/api/kick_sessions?local_port=554

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)
    local_port N 筛选本机端口，例如筛选rtsp链接：554
    peer_ip N 筛选客户端ip

  • 响应：

    {
   "code" : 0,
   "count_hit" : 1,# 筛选命中客户端个数
   "msg" : "success"
}

12、/index/api/addStreamProxy

  • 功能：动态添加rtsp/rtmp/hls/http-ts/http-flv拉流代理(只支持H264/H265/aac/G711/opus负载)

  • 范例：http://127.0.0.1/index/api/addStreamProxy?vhost=__defaultVhost__&app=proxy&stream=0&url=rtmp://live.hkstv.hk.lxdns.com/live/hks2

  • 参数：

    参数 参数类型 释意 是否必选
    secret string api操作密钥(配置文件配置) Y
    vhost string 添加的流的虚拟主机，例如__defaultVhost__ Y
    app string 添加的流的应用名，例如live Y
    stream string 添加的流的id名，例如test Y
    url string 拉流地址，例如rtmp://live.hkstv.hk.lxdns.com/live/hks2 Y
    retry_count int 拉流重试次数，默认为-1无限重试 N
    rtp_type int rtsp拉流时，拉流方式，0：tcp，1：udp，2：组播 N
    timeout_sec int 拉流超时时间，单位秒，float类型 N
    enable_hls bool 是否转换成hls-mpegts协议 N
    enable_hls_fmp4 bool 是否转换成hls-fmp4协议 N
    enable_mp4 bool 是否允许mp4录制 N
    enable_rtsp bool 是否转rtsp协议 N
    enable_rtmp bool 是否转rtmp/flv协议 N
    enable_ts bool 是否转http-ts/ws-ts协议 N
    enable_fmp4 bool 是否转http-fmp4/ws-fmp4协议 N
    hls_demand bool 该协议是否有人观看才生成 N
    rtsp_demand bool 该协议是否有人观看才生成 N
    rtmp_demand bool 该协议是否有人观看才生成 N
    ts_demand bool 该协议是否有人观看才生成 N
    fmp4_demand bool 该协议是否有人观看才生成 N
    enable_audio bool 转协议时是否开启音频 N
    add_mute_audio bool 转协议时，无音频是否添加静音aac音频 N
    mp4_save_path string mp4录制文件保存根目录，置空使用默认 N
    mp4_max_second int mp4录制切片大小，单位秒 N
    mp4_as_player bool MP4录制是否当作观看者参与播放人数计数 N
    hls_save_path string hls文件保存保存根目录，置空使用默认 N
    modify_stamp int 该流是否开启时间戳覆盖(0:绝对时间戳/1:系统时间戳/2:相对时间戳) N
    auto_close bool 无人观看是否自动关闭流(不触发无人观看hook) N

  • 响应：

    {
   "code" : 0,
   "data" : {
      "key" : "__defaultVhost__/proxy/0"  # 流的唯一标识
   }
}

13、/index/api/delStreamProxy(流注册成功后，也可以使用close_streams接口替代)

14、/index/api/addFFmpegSource

15、/index/api/delFFmpegSource(流注册成功后，也可以使用close_streams接口替代)

16、/index/api/isMediaOnline(已过期，请使用getMediaList接口替代)

17、/index/api/getMediaInfo(已过期，请使用getMediaList接口替代)

  • 功能：获取流相关信息

  • 范例：http://127.0.0.1/index/api/getMediaInfo?schema=rtsp&vhost=__defaultVhost__&app=live&stream=obs

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)
    schema Y 协议，例如 rtsp或rtmp
    vhost Y 虚拟主机，例如__defaultVhost__
    app Y 应用名，例如 live
    stream Y 流id，例如 obs

  • 响应：

    {
  "code" : 0,
  "online" : true, # 是否在线
  "readerCount" : 0, # 本协议观看人数
  "totalReaderCount" : 0, # 观看总人数，包括hls/rtsp/rtmp/http-flv/ws-flv
  "tracks" : [ # 轨道列表
        {
           "channels" : 1, # 音频通道数
           "codec_id" : 2, # H264 = 0, H265 = 1, AAC = 2, G711A = 3, G711U = 4
           "codec_id_name" : "CodecAAC", # 编码类型名称 
           "codec_type" : 1, # Video = 0, Audio = 1
           "ready" : true, # 轨道是否准备就绪
           "sample_bit" : 16, # 音频采样位数
           "sample_rate" : 8000 # 音频采样率
        },
        {
           "codec_id" : 0, # H264 = 0, H265 = 1, AAC = 2, G711A = 3, G711U = 4
           "codec_id_name" : "CodecH264", # 编码类型名称  
           "codec_type" : 0, # Video = 0, Audio = 1
           "fps" : 59,  # 视频fps
           "height" : 720, # 视频高
           "ready" : true,  # 轨道是否准备就绪
           "width" : 1280 # 视频宽
        }
  ]
}

18、/index/api/getRtpInfo

  • 功能：获取rtp代理时的某路ssrc rtp信息

  • 范例：http://127.0.0.1/index/api/getRtpInfo?stream_id=1A2B3C4D

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)
    stream_id Y RTP的ssrc，16进制字符串或者是流的id(openRtpServer接口指定)

  • 响应：

    {
   "code" : 0,
   "exist" : true, # 是否存在
   "peer_ip" : "192.168.0.23", # 推流客户端ip
   "peer_port" : 54000 # 客户端端口号
   "local_ip" : "0.0.0.0", #本地监听的网卡ip
   "local_port" : 10000
}

19、/index/api/getMP4RecordFile

  • 功能：搜索文件系统，获取流对应的录像文件列表或日期文件夹列表

  • 范例：http://127.0.0.1/index/api/getMP4RecordFile?vhost=__defaultVhost__&app=live&stream=ss&period=2020-01

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)
    vhost Y 流的虚拟主机名
    app Y 流的应用名
    stream Y 流的ID
    period N 流的录像日期，格式为2020-02-01,如果不是完整的日期，那么是搜索录像文件夹列表，否则搜索对应日期下的mp4文件列表
    customized_path N 自定义搜索路径，与startRecord方法中的customized_path一样，默认为配置文件的路径

  • 响应：

    # 搜索文件夹列表(按照前缀匹配规则)：period = 2020-01
{
   "code" : 0,
   "data" : {
      "paths" : [ "2020-01-25", "2020-01-24" ],
      "rootPath" : "/www/record/live/ss/"
   }
}

# 搜索mp4文件列表：period = 2020-01-24
{
   "code" : 0,
   "data" : {
      "paths" : [
         "22-20-30.mp4",
         "22-13-12.mp4",
         "21-57-07.mp4",
         "21-19-18.mp4",
         "21-24-21.mp4",
         "21-15-10.mp4",
         "22-14-14.mp4"
      ],
      "rootPath" : "/www/live/ss/2020-01-24/"
   }
}

20、/index/api/startRecord

  • 功能：开始录制hls或MP4

  • 范例：http://127.0.0.1/index/api/startRecord?type=1&vhost=__defaultVhost__&app=live&stream=obs

  • 参数：

    参数 是否必选 释意 类型
    secret Y api操作密钥(配置文件配置) string
    type Y 0为hls，1为mp4 0/1
    vhost Y 虚拟主机，例如__defaultVhost__ string
    app Y 应用名，例如 live string
    stream Y 流id，例如 obs string
    customized_path N 录像保存目录 string
    max_second N mp4录像切片时间大小,单位秒，置0则采用配置项 int

  • 响应：

    {
   "code" : 0,
   "result" : true # 成功与否
}

21、/index/api/stopRecord

22、/index/api/isRecording

23、/index/api/getSnap

  • 功能：获取截图或生成实时截图并返回

  • 范例：http://127.0.0.1/index/api/getSnap?url=rtmp://127.0.0.1/record/robot.mp4&timeout_sec=10&expire_sec=30

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)
    url Y 需要截图的url，可以是本机的，也可以是远程主机的
    timeout_sec Y 截图失败超时时间，防止FFmpeg一直等待截图
    expire_sec Y 截图的过期时间，该时间内产生的截图都会作为缓存返回

  • 响应：

    jpeg格式的图片，可以在浏览器直接打开

24、/index/api/openRtpServer

  • 功能：创建GB28181 RTP接收端口，如果该端口接收数据超时，则会自动被回收(不用调用closeRtpServer接口)

  • 范例：http://127.0.0.1/index/api/openRtpServer?port=0&tcp_mode=1&stream_id=test

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)
    port Y 接收端口，0则为随机端口
    tcp_mode Y 0 udp 模式，1 tcp 被动模式, 2 tcp 主动模式。 (兼容enable_tcp 为0/1)
    stream_id Y 该端口绑定的流ID，该端口只能创建这一个流(而不是根据ssrc创建多个)

  • 响应：

    {
   "code" : 0,
   "port" : 55463 #接收端口，方便获取随机端口号
}

25、/index/api/closeRtpServer

  • 功能：关闭GB28181 RTP接收端口

  • 范例：http://127.0.0.1/index/api/closeRtpServer?stream_id=test

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)
    stream_id Y 调用openRtpServer接口时提供的流ID

  • 响应：

    {
   "code": 0,
   "hit": 1 #是否找到记录并关闭
}

26、/index/api/listRtpServer

  • 功能：获取openRtpServer接口创建的所有RTP服务器

  • 范例：http://127.0.0.1/index/api/listRtpServer

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)

  • 响应：

    {
   "code" : 0,
   "data" : [
      {
         "port" : 52183, #绑定的端口号
         "stream_id" : "test" #绑定的流ID
      }
   ]
}

27、/index/api/startSendRtp

  • 功能：作为GB28181客户端，启动ps-rtp推流，支持rtp/udp方式；该接口支持rtsp/rtmp等协议转ps-rtp推流。第一次推流失败会直接返回错误，成功一次后，后续失败也将无限重试。

  • 范例：http://127.0.0.1/index/api/startSendRtp?secret=035c73f7-bb6b-4889-a715-d9eb2d1925cc&vhost=__defaultVhost__&app=live&stream=test&ssrc=1&dst_url=127.0.0.1&dst_port=10000&is_udp=0

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)
    vhost Y 虚拟主机，例如__defaultVhost__
    app Y 应用名，例如 live
    stream Y 流id，例如 test
    ssrc Y 推流的rtp的ssrc,指定不同的ssrc可以同时推流到多个服务器
    dst_url Y 目标ip或域名
    dst_port Y 目标端口
    is_udp Y 是否为udp模式,否则为tcp模式
    src_port N 使用的本机端口，为0或不传时默认为随机端口
    pt N 发送时，rtp的pt（uint8_t）,不传时默认为96
    use_ps N 发送时，rtp的负载类型。为1时，负载为ps；为0时，为es；不传时默认为1
    only_audio N 当use_ps 为0时，有效。为1时，发送音频；为0时，发送视频；不传时默认为0

  • 响应：

    {
   "code": 0, #成功
   "local_port": 57152 #使用的本地端口号 
}

27.1 、/index/api/startSendRtpPassive

  • 功能：作为GB28181 Passive TCP服务器；该接口支持rtsp/rtmp等协议转ps-rtp被动推流。调用该接口，zlm会启动tcp服务器等待连接请求，连接建立后，zlm会关闭tcp服务器，然后源源不断的往客户端推流。第一次推流失败会直接返回错误，成功一次后，后续失败也将无限重试(不停地建立tcp监听，超时后再关闭)。

  • 范例：http://127.0.0.1/index/api/startSendRtpPassive?secret=035c73f7-bb6b-4889-a715-d9eb2d1925cc&vhost=__defaultVhost__&app=live&stream=test&ssrc=1

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)
    vhost Y 虚拟主机，例如__defaultVhost__
    app Y 应用名，例如 live
    stream Y 流id，例如 test
    ssrc Y 推流的rtp的ssrc,指定不同的ssrc可以同时推流到多个服务器
    src_port N 使用的本机端口，为0或不传时默认为随机端口
    pt N 发送时，rtp的pt（uint8_t）,不传时默认为96
    use_ps N 发送时，rtp的负载类型。为1时，负载为ps；为0时，为es；不传时默认为1
    only_audio N 当use_ps 为0时，有效。为1时，发送音频；为0时，发送视频；不传时默认为0

  • 响应：

    {
   "code": 0, #成功
   "local_port": 57152 #使用的本地端口号 
}

28、/index/api/stopSendRtp

29、/index/api/getStatistic

  • 功能：获取主要对象个数统计，主要用于分析内存性能

  • 范例：http://127.0.0.1/index/api/getStatistic?secret=035c73f7-bb6b-4889-a715-d9eb2d1925cc

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)

  • 响应：

    {
"code": 0,
"data": {
    "Buffer": 2,
    "BufferLikeString": 1,
    "BufferList": 0,
    "BufferRaw": 1,
    "Frame": 0,
    "FrameImp": 0,
    "MediaSource": 0,
    "MultiMediaSourceMuxer": 0,
    "Socket": 66,
    "TcpClient": 0,
    "TcpServer": 64,
    "TcpSession": 1
}
}

30、/index/api/addStreamPusherProxy

  • 功能：添加rtsp/rtmp主动推流(把本服务器的直播流推送到其他服务器去)

  • 范例：http://127.0.0.1/index/api/addStreamPusherProxy?vhost=__defaultVhost__&app=proxy&stream=test&dst_url=rtmp://127.0.0.1/live/test2

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)
    vhost Y 添加的流的虚拟主机，例如__defaultVhost__
    schema Y 协议，例如 rtsp或rtmp
    app Y 添加的流的应用名，例如live
    stream Y 需要转推的流id
    dst_url Y 目标转推url，带参数需要自行url转义
    retry_count N 转推失败重试次数，默认无限重试
    rtp_type N rtsp推流时，推流方式，0：tcp，1：udp
    timeout_sec N 推流超时时间，单位秒，float类型

  • 响应：

    {
   "code" : 0,
   "data" : {
      "key" : "rtmp/__defaultVhost__/proxy/test/4AB43C9EABEB76AB443BB8260C8B2D12"  # 流的唯一标识
   }
}

31、/index/api/delStreamPusherProxy(可以使用close_streams接口关闭源直播流也可以停止推流)

32、/index/api/version(获取版本信息)

  • 功能：获取版本信息，如分支，commit id, 编译时间

  • 范例：http://127.0.0.1/index/api/version

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)

  • 响应：

    {
  "code": 0,
  "data": {
      "branchName": "master",
      "buildTime": "2023-04-19T10:34:34",
      "commitHash": "f143898"
   }
}

33、/index/api/getMediaPlayerList 

{
    "code": 0,
    "data": [
        {
            "identifier": "3-309",
            "local_ip": "::",
            "local_port": 8000,
            "peer_ip": "172.18.190.159",
            "peer_port": 52996,
            "typeid": "mediakit::WebRtcSession"
        }
    ]
}

34、VideoStack多视频流拼接宫格功能

如需使用该功能，需要编译时开启 ENABLE_VIDEOSTACK、ENABLE_FFMPEG 和 ENABLE_X264

⚠️注意： 需关闭cpu亲和性 （启动命令后面添加--affinity=0 完整示例： MediaServer.exe --affinity=0 ）

34.1 添加多屏拼接 (/index/api/stack/start)

  • 方法: POST

  • 参数:

    参数名 描述 备注
    gapv 垂直间隙比例 可不填，则默认为0
    gaph 水平间隙比例 可不填，则默认为0
    width 拼接后的视频宽度
    height 拼接后的视频高度
    url 视频流URL列表 需要拼接的视频流(RTSP/RTMP)；数组元素数量和数组个数需与row和col对应，具体的url可为空字符串，取不到流时会填充一张默认的断流图片
    id 拼接任务的唯一标识 该示例中为stack_test，则取流url为：rtsp://ip/live/stack_test  (其他类型的流取流规则与常规流相同)
    row 宫格的行数
    col 宫格的列数
    span 自定义宫格跨度配置 把指定的格子合并为一个大格子  (焦点屏) ；可不填

  • 请求示例:

{
    "id": "stack_test",
    "row": 4,
    "col": 4,
    "gapv": 0.002,
    "gaph": 0.001,
    "width": 1920,
    "height": 1080,
    "url": [
        [
            "rtsp://example.com/live/stream1",
            "rtsp://example.com/live/stream2",
            "rtsp://example.com/live/stream3",
            "rtsp://example.com/live/stream4"
        ],
        [
            "rtsp://example.com/live/stream5",
            "rtsp://example.com/live/stream6",
            "rtsp://example.com/live/stream7",
            "rtsp://example.com/live/stream8"
        ],
        [
            "rtsp://example.com/live/stream9",
            "rtsp://example.com/live/stream10",
            "rtsp://example.com/live/stream11",
            "rtsp://example.com/live/stream12"
        ],
        [
            "rtsp://example.com/live/stream13",
            "rtsp://example.com/live/stream14",
            "rtsp://example.com/live/stream15",
            "rtsp://example.com/live/stream16"
        ]
    ],
    "span": [
                [
                    [0, 0], [1, 1]
                ], 
                [
                    [3, 2], [3, 3]
                ]
            ]
}

34.2 变更拼接参数 (/index/api/stack/reset)

该接口参数与start相同，可用于在不断流的情况下，变更拼接参数，实现类似于切屏的效果

34.3 关闭多屏拼接 (/index/api/stack/stop)

已默认添加了当触发无人观看时，自动关闭（该接口用于主动关闭）

  • 方法: GET
  • 参数说明:
参数名 描述 备注
id 拼接任务的唯一标识
  • 拼接示意图(4行4列)，对应上面的示例json，如果span参数为空数组时，则为均分的宫格屏

videostack

35、/index/api/deleteSnapDirectory

36、/index/api/deleteRecordDirectory

37、/index/api/startRecordTask

38、/index/api/setRecordSpeed

39、/index/api/seekRecordStamp

40、/index/api/listStreamProxy

41、/index/api/listStreamPusherProxy

42、/index/api/listFFmpegSource

43、/index/api/broadcastMessage

44、/index/api/openRtpServerMultiplex

  • 功能：创建多路复用GB28181 RTP接收端口

  • 范例：http://127.0.0.1/index/api/openRtpServerMultiplex?port=0&tcp_mode=1&stream_id=test

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)
    port Y 绑定的端口，0时为随机端口
    tcp_mode Y tcp模式，0时为不启用tcp监听，1时为启用tcp监听
    stream_id Y 该端口绑定的流id
    only_track N 是否为单音频/单视频track，0：不设置，1：单音频，2：单视频
    local_ip N 指定创建RTP的本地ip，ipv4可填"0.0.0.0"，ipv6可填"::"

45、/index/api/connectRtpServer

46、/index/api/updateRtpServerSSRC

47、/index/api/pauseRtpCheck

  • 功能：暂停RTP超时检查

  • 范例：http://127.0.0.1/index/api/pauseRtpCheck?stream_id=test

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)
    stream_id Y 该端口绑定的流id
    pause_seconds N 暂停超时监测后，将在pause_seconds时间后恢复

48、/index/api/resumeRtpCheck

49、/index/api/startSendRtpTalk

  • 功能：开始双向对讲，作为GB28181客户端启动rtp推流并接收对方rtp流

  • 范例：http://127.0.0.1/index/api/startSendRtpTalk?vhost=__defaultVhost__&app=rtp&stream=rtc&ssrc=1&recv_stream_id=test

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)
    vhost Y 虚拟主机，例如__defaultVhost__
    app Y 应用名，例如 rtp
    stream Y 流id，例如webrtc推流上来的流id
    ssrc Y rtp推流出去的ssrc
    recv_stream_id Y 对方rtp推流上来的流id，通过这个链接回复rtp流；两个流的app和vhost需一致
    from_mp4 N 是否推送本地MP4录像
    type N 0(ES流)、1(PS流)、2(TS流)，默认1(PS流)
    pt N rtp payload type，默认96
    only_audio N rtp es方式打包时，是否只打包音频
    enable_origin_recv_limit N 转发rtp(tcp模式)时，发送不出去是否限制源端收流速度

50、/index/api/listRtpSender

51、/index/api/getProxyInfo

52、/index/api/getProxyPusherInfo

53、/index/api/loadMP4File

  • 功能：点播mp4文件，生成一个直播流

  • 范例：http://127.0.0.1/index/api/loadMP4File?vhost=__defaultVhost__&app=live&stream=test&file_path=/path/to/mp4/file.mp4

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)
    vhost Y 添加的流的虚拟主机，例如__defaultVhost__
    app Y 添加的流的应用名，例如live
    stream Y 添加的流的id名，例如test
    file_path Y mp4文件绝对路径
    file_repeat N 是否循环点播mp4文件，如果配置文件已开启循环则此参数无效
    seek_ms N 点播seek到特定位置，单位毫秒
    speed N 播放速度，float类型
    enable_hls N 是否转hls-ts
    enable_hls_fmp4 N 是否转hls-fmp4
    enable_mp4 N 是否mp4录制
    enable_rtsp N 是否转协议为rtsp/webrtc
    enable_rtmp N 是否转协议为rtmp/flv
    enable_ts N 是否转协议为http-ts/ws-ts
    enable_fmp4 N 是否转协议为http-fmp4/ws-fmp4
    enable_audio N 转协议是否开启音频
    add_mute_audio N 转协议无音频时，是否添加静音aac音频
    mp4_save_path N mp4录制保存根目录，置空使用默认目录
    mp4_max_second N mp4录制切片大小，单位秒
    hls_save_path N hls保存根目录，置空使用默认目录
    modify_stamp N 是否修改原始时间戳(0:绝对时间戳/1:系统时间戳/2:相对时间戳)
    auto_close N 无人观看时是否直接关闭(不触发on_none_reader hook)

54、/index/api/downloadFile

55、/index/api/downloadBin

56、/index/api/webrtc

  • 功能：WebRTC交互接口

  • 范例：POST http://127.0.0.1/index/api/webrtc?type=play&app=live&stream=test

  • 请求方法：POST，Content-Type: application/json，body为SDP offer

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)
    type Y webrtc类型，play为播放，push为推流，echo为回显测试
    app Y 应用名，例如 live
    stream Y 流id，例如 test
    preferred_tcp N 是否webrtc over tcp优先模式
    cand_udp N 指定zlm服务器udp candidate
    cand_tcp N 指定zlm服务器tcp candidate

57、/index/api/whip

  • 功能：WebRTC WHIP标准推流接口

  • 范例：POST http://127.0.0.1/index/api/whip?app=live&stream=test

  • 请求方法：POST，Content-Type: application/sdp，body为SDP offer

  • 参数：

    参数 是否必选 释意
    app Y 应用名，例如 live
    stream Y 流id，例如 test
    preferred_tcp N 是否webrtc over tcp优先模式
    cand_udp N 指定zlm服务器udp candidate
    cand_tcp N 指定zlm服务器tcp candidate

  • 响应：成功返回201状态码，Content-Type: application/sdp，body为SDP answer。响应头中Location字段包含delete_webrtc接口的URL。

58、/index/api/whep

  • 功能：WebRTC WHEP标准播放接口

  • 范例：POST http://127.0.0.1/index/api/whep?app=live&stream=test

  • 请求方法：POST，Content-Type: application/sdp，body为SDP offer

  • 参数：

    参数 是否必选 释意
    app Y 应用名，例如 live
    stream Y 流id，例如 test
    preferred_tcp N 是否webrtc over tcp优先模式
    cand_udp N 指定zlm服务器udp candidate
    cand_tcp N 指定zlm服务器tcp candidate

  • 响应：成功返回201状态码，Content-Type: application/sdp，body为SDP answer。响应头中Location字段包含delete_webrtc接口的URL。

59、/index/api/delete_webrtc

  • 功能：删除WebRTC连接

  • 范例：DELETE http://127.0.0.1/index/api/delete_webrtc?id=xxx&token=xxx

  • 请求方法：DELETE

  • 参数：

    参数 是否必选 释意
    id Y WebRTC连接的唯一标识
    token Y 删除操作的验证token

  • 说明：id和token由whip/whep接口返回的Location响应头中获取。

60、/index/api/addWebrtcRoomKeeper

61、/index/api/delWebrtcRoomKeeper

62、/index/api/listWebrtcRoomKeepers

63、/index/api/listWebrtcRooms

64、/index/api/getWebrtcProxyPlayerInfo

65、/index/api/searchOnvifDevice

66、/index/api/getStreamUrl

67、/index/api/login

  • 功能：登录接口

  • 范例：http://127.0.0.1/index/api/login?digest=xxx

  • 参数：

    参数 是否必选 释意
    digest Y MD5("zlmediakit:" + ${secret} + ":" + ${cookie})

  • 注意：配置文件api.legacyAuth须设置为0

68、/index/api/logout

测试文档

使用教程

相关文档和资源

代码解读

Use tutorial

Clone this wiki locally