Mirror/ZLMediaKit
1
0
Fork 0
mirror of https://github.com/ZLMediaKit/ZLMediaKit.git synced 2026-06-12 19:24:22 +08:00
Code Issues Packages Projects Releases Wiki Activity
Page: MediaServer支持的HTTP API
Pages
Benchmark Dependency and Copyright GB28181 SIP信令抓包 GB28181怎么用设备ID作为流ID GB28181推流 HTTP文件服务器优化：获取文件大小 Home How to create a live steam MediaServer支持的HTTP API MediaServer支持的HTTP HOOK API Playing URL Rules Quick Start RTMP对H265和OPUS的支持 RTMP播放兼容性问题 RTSP性能优化 RTSP推流流程 Starting and Stopping the Server VideoStack多视频流拼接宫格功能 Windows 版编译说明 ZLMediaKit Python混合编程模式 ZLMediaKit实现按需拉流 ZLMediaKit实现推流鉴权 ZLMediaKit实现播放鉴权 ZLMediaKit推流测试 ZLMediaKit高并发实现原理 ZLMediakit独家特性介绍 postman 自动生成的restful api接口 rtmp拉流性能测试 rtmp推流性能测试 rtsp拉流性能测试 rtsp推流性能测试 vcpkg方式安装zlmediakit webrtc信令交互格式 zlmediakit webrtc重磅更新 zlmediakit对vp8 vp9 av1编码的全面支持 zlmediakit的hls高性能之旅 zlm启用webrtc编译指南 为什么不建议QQ私聊咨询问题？ 代码依赖与版权声明 代码篇之onceToken 使用ZLMediaKit实现按需推流 在线测试 延时测试 快速开始 怎么开启https相关功能 怎么测试ZLMediaKit的延时？ 性能测试 播放url规则 时序图 服务器的启动与关闭 流媒体相关技术介绍 生成SSL自签名证书并测试 直播延时的本质 视频会议相关资源 配置文件详解
Clone
92
MediaServer支持的HTTP API
xiongziliang edited this page 2026-03-17 20:48:37 +08:00
Unescape Escape
Table of Contents
This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

下载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