Files

Haibo Chen(陈海博) f59c92162b doc (#29 )

* update log

* update log level

* Enhance config.yaml by adding a comment for log-level options

* update log

* Refactor SIP service start method to accept configuration parameter for log level management

* 增加文档

2025-08-26 13:59:18 +08:00

12 KiB

Raw Blame History

SRS-SIP API 接口文档

概述

SRS-SIP 是一个基于 GB28181 协议的视频监控系统，提供设备管理、视频流控制、PTZ控制等功能。本文档描述了系统提供的 HTTP API 接口。

基础信息：

基础URL: /srs-sip/v1
内容类型: application/json
响应格式: JSON

通用响应格式

所有API接口都使用统一的响应格式：

{
  "code": 0,
  "data": {}
}

code: 状态码，0表示成功，其他值表示错误
data: 响应数据，具体内容根据接口而定

1. 系统信息接口

1.1 获取API版本信息

接口地址： GET /srs-sip

描述： 获取API版本信息

响应示例：

{
  "version": "v1"
}

1.2 获取所有API路由

接口地址： GET /srs-sip/v1

描述： 获取系统所有可用的API路由列表

响应示例：

{
  "code": 0,
  "data": [
    {
      "method": "GET",
      "path": "/srs-sip/v1/devices"
    },
    {
      "method": "POST",
      "path": "/srs-sip/v1/invite"
    }
  ]
}

2. 设备管理接口

2.1 获取设备列表

接口地址： GET /srs-sip/v1/devices

描述： 获取所有已注册的设备列表

响应示例：

{
  "code": 0,
  "data": [
    {
      "device_id": "34020000001320000001",
      "source_addr": "192.168.1.100:5060",
      "network_type": "UDP",
      "online": true,
      "heart_beat_interval": 60,
      "heart_beat_count": 3
    }
  ]
}

响应字段说明：

device_id: 设备ID
source_addr: 设备源地址
network_type: 网络类型（UDP/TCP）
online: 设备在线状态
heart_beat_interval: 心跳间隔时间（秒）
heart_beat_count: 心跳超时次数

2.2 获取设备通道列表

接口地址： GET /srs-sip/v1/devices/{id}/channels

描述： 获取指定设备的所有通道信息

路径参数：

id: 设备ID

响应示例：

{
  "code": 0,
  "data": [
    {
      "device_id": "34020000001320000002",
      "parent_id": "34020000001320000001",
      "name": "摄像头01",
      "manufacturer": "HIKVISION",
      "model": "DS-2CD2T47G1-L",
      "owner": "Camera Owner",
      "civil_code": "320100",
      "address": "测试地址",
      "port": 5060,
      "parental": 1,
      "safety_way": 0,
      "register_way": 1,
      "secrecy": 0,
      "ip_address": "192.168.1.100",
      "status": "ON",
      "longitude": 120.123456,
      "latitude": 30.123456,
      "info": {
        "ptz_type": 1,
        "resolution": "1920*1080",
        "download_speed": "4"
      },
      "ssrc": "1234567890"
    }
  ]
}

2.3 获取所有通道列表

接口地址： GET /srs-sip/v1/channels

描述： 获取系统中所有设备的通道信息

响应格式： 与2.2接口相同，返回所有设备的通道列表

3. 视频流控制接口

3.1 发起视频邀请

接口地址： POST /srs-sip/v1/invite

描述： 向指定通道发起视频流邀请

请求参数：

{
  "device_id": "34020000001320000001",
  "channel_id": "34020000001320000002",
  "media_server_id": 1,
  "play_type": 0,
  "sub_stream": 0,
  "start_time": 1640995200,
  "end_time": 1640998800
}

参数说明：

device_id: 设备ID
channel_id: 通道ID
media_server_id: 媒体服务器ID
play_type: 播放类型（0:实时播放, 1:回放, 2:下载）
sub_stream: 子码流（0:主码流, 1:子码流）
start_time: 开始时间（Unix时间戳，回放时使用）
end_time: 结束时间（Unix时间戳，回放时使用）

响应示例：

{
  "code": 0,
  "data": {
    "channel_id": "34020000001320000002",
    "url": "rtmp://192.168.1.200:1935/live/34020000001320000002"
  }
}

3.2 结束视频会话

接口地址： POST /srs-sip/v1/bye

描述： 结束指定的视频会话

请求参数：

{
  "device_id": "34020000001320000001",
  "channel_id": "34020000001320000002",
  "url": "rtmp://192.168.1.200:1935/live/34020000001320000002"
}

响应示例：

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

3.3 暂停视频流

接口地址： POST /srs-sip/v1/pause

描述： 暂停指定的视频流

请求参数：

{
  "device_id": "34020000001320000001",
  "channel_id": "34020000001320000002",
  "url": "rtmp://192.168.1.200:1935/live/34020000001320000002"
}

3.4 恢复视频流

接口地址： POST /srs-sip/v1/resume

描述： 恢复已暂停的视频流

请求参数： 与暂停接口相同

3.5 调整播放速度

接口地址： POST /srs-sip/v1/speed

描述： 调整视频播放速度（用于回放）

请求参数：

{
  "device_id": "34020000001320000001",
  "channel_id": "34020000001320000002",
  "url": "rtmp://192.168.1.200:1935/live/34020000001320000002",
  "speed": 2.0
}

参数说明：

speed: 播放速度倍数（0.5表示0.5倍速，2.0表示2倍速）

4. PTZ控制接口

4.1 PTZ控制

接口地址： POST /srs-sip/v1/ptz

描述： 控制摄像头的PTZ（云台）功能

请求参数：

{
  "device_id": "34020000001320000001",
  "channel_id": "34020000001320000002",
  "ptz": "up",
  "speed": "5"
}

参数说明：

ptz: PTZ控制命令
- up: 向上
- down: 向下
- left: 向左
- right: 向右
- zoom_in: 放大
- zoom_out: 缩小
- stop: 停止
speed: 控制速度（1-9）

响应示例：

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

5. 录像查询接口

5.1 查询录像记录

接口地址： POST /srs-sip/v1/query-record

描述： 查询指定设备通道的录像记录

请求参数：

{
  "device_id": "34020000001320000001",
  "channel_id": "34020000001320000002",
  "start_time": 1640995200,
  "end_time": 1640998800
}

参数说明：

device_id: 设备ID
channel_id: 通道ID
start_time: 查询开始时间（Unix时间戳）
end_time: 查询结束时间（Unix时间戳）

响应示例：

{
  "code": 0,
  "data": [
    {
      "device_id": "34020000001320000002",
      "name": "录像文件01",
      "file_path": "/record/20220101/001.mp4",
      "address": "192.168.1.100",
      "start_time": "2022-01-01T10:00:00Z",
      "end_time": "2022-01-01T11:00:00Z",
      "secrecy": 0,
      "type": "time"
    }
  ]
}

响应字段说明：

device_id: 设备ID
name: 录像文件名称
file_path: 录像文件路径
address: 录像文件地址
start_time: 录像开始时间
end_time: 录像结束时间
secrecy: 保密属性（0:不保密, 1:保密）
type: 录像类型

6. 媒体服务器管理接口

6.1 获取媒体服务器列表

接口地址： GET /srs-sip/v1/media-servers

描述： 获取所有已配置的媒体服务器列表

响应示例：

{
  "code": 0,
  "data": [
    {
      "id": 1,
      "name": "SRS服务器01",
      "type": "SRS",
      "ip": "192.168.1.200",
      "port": 1935,
      "username": "admin",
      "password": "123456",
      "secret": "secret_key",
      "is_default": 1,
      "created_at": "2022-01-01T10:00:00Z"
    }
  ]
}

响应字段说明：

id: 媒体服务器ID
name: 服务器名称
type: 服务器类型（SRS、ZLM等）
ip: 服务器IP地址
port: 服务器端口
username: 用户名
password: 密码
secret: 密钥
is_default: 是否为默认服务器（1:是, 0:否）
created_at: 创建时间

6.2 添加媒体服务器

接口地址： POST /srs-sip/v1/media-servers

描述： 添加新的媒体服务器配置

请求参数：

{
  "name": "SRS服务器02",
  "type": "SRS",
  "ip": "192.168.1.201",
  "port": 1935,
  "username": "admin",
  "password": "123456",
  "secret": "secret_key",
  "is_default": 0
}

参数说明：

name: 服务器名称（必填）
type: 服务器类型（必填，支持SRS、ZLM等）
ip: 服务器IP地址（必填）
port: 服务器端口（必填）
username: 用户名（可选）
password: 密码（可选）
secret: 密钥（可选）
is_default: 是否设为默认服务器（可选，默认为0）

响应示例：

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

6.3 删除媒体服务器

接口地址： DELETE /srs-sip/v1/media-servers/{id}

描述： 删除指定的媒体服务器配置

路径参数：

id: 媒体服务器ID

响应示例：

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

6.4 设置默认媒体服务器

接口地址： POST /srs-sip/v1/media-servers/default/{id}

描述： 将指定的媒体服务器设置为默认服务器

路径参数：

id: 媒体服务器ID

响应示例：

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

7. 错误码说明

错误码	HTTP状态码	说明
0	200	成功
400	400	请求参数错误
500	500	服务器内部错误

8. 使用示例

8.1 获取设备列表并播放视频

# 1. 获取设备列表
curl -X GET "http://localhost:8080/srs-sip/v1/devices"

# 2. 获取设备通道
curl -X GET "http://localhost:8080/srs-sip/v1/devices/34020000001320000001/channels"

# 3. 发起视频邀请
curl -X POST "http://localhost:8080/srs-sip/v1/invite" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "34020000001320000001",
    "channel_id": "34020000001320000002",
    "media_server_id": 1,
    "play_type": 0,
    "sub_stream": 0
  }'

8.2 PTZ控制示例

# 控制摄像头向上移动
curl -X POST "http://localhost:8080/srs-sip/v1/ptz" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "34020000001320000001",
    "channel_id": "34020000001320000002",
    "ptz": "up",
    "speed": "5"
  }'

# 停止PTZ控制
curl -X POST "http://localhost:8080/srs-sip/v1/ptz" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "34020000001320000001",
    "channel_id": "34020000001320000002",
    "ptz": "stop",
    "speed": "0"
  }'

8.3 录像查询和回放示例

# 查询录像记录
curl -X POST "http://localhost:8080/srs-sip/v1/query-record" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "34020000001320000001",
    "channel_id": "34020000001320000002",
    "start_time": 1640995200,
    "end_time": 1640998800
  }'

# 回放录像
curl -X POST "http://localhost:8080/srs-sip/v1/invite" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "34020000001320000001",
    "channel_id": "34020000001320000002",
    "media_server_id": 1,
    "play_type": 1,
    "start_time": 1640995200,
    "end_time": 1640998800
  }'

9. 注意事项

设备ID格式：设备ID需要符合GB28181标准，通常为20位数字
时间格式：所有时间参数使用Unix时间戳格式
媒体服务器：在发起视频邀请前，需要确保已配置可用的媒体服务器
网络连接：确保SIP服务器与设备、媒体服务器之间网络连通
权限控制：部分接口可能需要认证，具体根据系统配置而定
设备状态：只有在线状态的设备才能进行视频邀请和PTZ控制
并发限制：同一通道同时只能有一个活跃的视频会话

10. 常见问题

Q1: 设备离线怎么办？

A: 检查设备网络连接，确保设备能正常发送心跳包到SIP服务器。

Q2: 视频邀请失败？

A: 检查媒体服务器状态，确保设备支持对应的编码格式。

Q3: PTZ控制无响应？

A: 确认设备支持PTZ功能，检查PTZ控制命令格式是否正确。

11. 更新日志

v1.0.0 (2024-01-01): 初始版本，包含基础的设备管理、视频控制、PTZ控制功能

12 KiB Raw Blame History Unescape Escape

SRS-SIP API 接口文档

概述

通用响应格式

1. 系统信息接口

1.1 获取API版本信息

1.2 获取所有API路由

2. 设备管理接口

2.1 获取设备列表

2.2 获取设备通道列表

2.3 获取所有通道列表

3. 视频流控制接口

3.1 发起视频邀请

3.2 结束视频会话

3.3 暂停视频流

3.4 恢复视频流

3.5 调整播放速度

4. PTZ控制接口

4.1 PTZ控制

5. 录像查询接口

5.1 查询录像记录

6. 媒体服务器管理接口

6.1 获取媒体服务器列表

6.2 添加媒体服务器

6.3 删除媒体服务器

6.4 设置默认媒体服务器

7. 错误码说明

8. 使用示例

8.1 获取设备列表并播放视频

8.2 PTZ控制示例

8.3 录像查询和回放示例

9. 注意事项

10. 常见问题

Q1: 设备离线怎么办？

Q2: 视频邀请失败？

Q3: PTZ控制无响应？

11. 更新日志

12 KiB

Raw Blame History