12 KiB
12 KiB
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: 设备IDsource_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: 设备IDchannel_id: 通道IDmedia_server_id: 媒体服务器IDplay_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: 向右zoomin: 放大zoomout: 缩小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: 设备IDchannel_id: 通道IDstart_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: 设备IDname: 录像文件名称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: 媒体服务器IDname: 服务器名称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控制功能