GB28181 API

GB28181 插件提供完整的 GB/T 28181 协议 API，支持国标设备的接入管理、通道查询、PTZ 云台控制、录像查询与回放，以及级联平台对接。

启用插件

features = ["gb28181"]

设备管理

查询设备列表

GET /gb28181/devices

返回所有已注册的国标设备。

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 2,
    "devices": [
      {
        "device_id": "34020000001320000001",
        "name": "前门摄像头",
        "manufacturer": "Hikvision",
        "model": "DS-2CD2T45",
        "firmware": "V5.6.2",
        "transport": "UDP",
        "status": "online",
        "ip": "192.168.1.100",
        "port": 5060,
        "register_time": "2026-03-18T08:00:00Z",
        "keepalive_time": "2026-03-18T14:30:00Z",
        "channel_count": 4
      }
    ]
  }
}

查询单个设备

GET /gb28181/device/{device_id}

返回指定设备的详细信息。

删除设备

DELETE /gb28181/device/{device_id}

从系统中移除指定设备。

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "device_id": "34020000001320000001",
    "status": "removed"
  }
}

刷新设备信息

POST /gb28181/device/{device_id}/refresh

向设备发送 Catalog 查询，刷新设备信息和通道列表。

通道管理

查询设备通道

GET /gb28181/device/{device_id}/channels

返回指定设备的所有通道。

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "device_id": "34020000001320000001",
    "total": 4,
    "channels": [
      {
        "channel_id": "34020000001310000001",
        "name": "通道1",
        "manufacturer": "Hikvision",
        "status": "ON",
        "ptz_type": 3,
        "longitude": 116.397428,
        "latitude": 39.90923,
        "has_audio": true
      }
    ]
  }
}

实时预览（Invite）

POST /gb28181/device/{device_id}/channel/{channel_id}/invite
Content-Type: application/json

{
  "stream_path": "gb/34020000001310000001",
  "transport": "TCP",
  "ssrc": ""
}

向设备发送 Invite 请求，开始实时视频预览。成功后流会发布到指定的 stream_path。

参数	类型	说明
stream_path	string	流发布路径（可选，默认自动生成）
transport	string	传输方式：UDP 或 TCP（默认 UDP）
ssrc	string	SSRC（可选，默认自动分配）

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "stream_path": "gb/34020000001310000001",
    "ssrc": "0200000001",
    "status": "inviting"
  }
}

停止预览（Bye）

POST /gb28181/device/{device_id}/channel/{channel_id}/bye

停止实时预览，向设备发送 BYE 请求。

PTZ 云台控制

发送 PTZ 命令

POST /gb28181/device/{device_id}/channel/{channel_id}/ptz
Content-Type: application/json

{
  "command": "left",
  "speed": 128,
  "priority": 1
}

控制摄像头的云台方向和镜头缩放。

命令列表

Command	说明
up	向上转动
down	向下转动
left	向左转动
right	向右转动
upleft	左上转动
upright	右上转动
downleft	左下转动
downright	右下转动
zoomin	镜头放大
zoomout	镜头缩小
focusnear	近焦
focusfar	远焦
irisin	光圈放大
irisout	光圈缩小
stop	停止运动

速度参数

参数	范围	说明
speed	1-255	转动速度，128 为中速
priority	0-15	控制优先级，值越大优先级越高

PTZ 控制示例

左转：

curl -X POST http://localhost:8080/gb28181/device/34020000001320000001/channel/34020000001310000001/ptz \
  -H "Content-Type: application/json" \
  -d '{"command": "left", "speed": 128}'

放大：

curl -X POST http://localhost:8080/gb28181/device/34020000001320000001/channel/34020000001310000001/ptz \
  -H "Content-Type: application/json" \
  -d '{"command": "zoomin", "speed": 64}'

停止：

curl -X POST http://localhost:8080/gb28181/device/34020000001320000001/channel/34020000001310000001/ptz \
  -H "Content-Type: application/json" \
  -d '{"command": "stop"}'

预置位控制

POST /gb28181/device/{device_id}/channel/{channel_id}/preset
Content-Type: application/json

{
  "action": "goto",
  "preset_id": 1
}

Action	说明
set	设置当前位置为预置位
goto	转到指定预置位
remove	删除预置位

录像查询

查询设备录像

POST /gb28181/device/{device_id}/channel/{channel_id}/records
Content-Type: application/json

{
  "start_time": "2026-03-18T00:00:00Z",
  "end_time": "2026-03-18T23:59:59Z",
  "type": "all",
  "page": 1,
  "page_size": 50
}

参数	类型	说明
start_time	RFC3339	查询起始时间
end_time	RFC3339	查询结束时间
type	string	录像类型：all、alarm、manual、timer
page	int	页码
page_size	int	每页数量

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 24,
    "records": [
      {
        "name": "record_001",
        "start_time": "2026-03-18T08:00:00Z",
        "end_time": "2026-03-18T09:00:00Z",
        "type": "timer",
        "file_size": 1073741824
      }
    ]
  }
}

录像回放

POST /gb28181/device/{device_id}/channel/{channel_id}/playback
Content-Type: application/json

{
  "start_time": "2026-03-18T08:00:00Z",
  "end_time": "2026-03-18T09:00:00Z",
  "stream_path": "playback/34020000001310000001",
  "speed": 1.0
}

发起录像回放请求，设备端推送录像数据到引擎。

参数	类型	说明
start_time	RFC3339	回放起始时间
end_time	RFC3339	回放结束时间
stream_path	string	回放流路径
speed	float	播放速度（0.25 / 0.5 / 1.0 / 2.0 / 4.0）

回放控制

POST /gb28181/device/{device_id}/channel/{channel_id}/playback/control
Content-Type: application/json

{
  "action": "pause"
}

Action	说明
pause	暂停回放
resume	恢复回放
speed	变速播放（附带 speed 参数）
seek	跳转到指定时间（附带 position 参数）
stop	停止回放

录像下载

POST /gb28181/device/{device_id}/channel/{channel_id}/download
Content-Type: application/json

{
  "start_time": "2026-03-18T08:00:00Z",
  "end_time": "2026-03-18T09:00:00Z",
  "speed": 4.0
}

以指定倍速下载设备录像文件到本地。

级联平台

查询级联平台

GET /gb28181/cascades

返回所有已配置的上级平台信息。

响应示例：

{
  "code": 0,
  "data": {
    "total": 1,
    "cascades": [
      {
        "platform_id": "34020000002000000001",
        "name": "市级平台",
        "address": "10.0.0.100:5060",
        "transport": "TCP",
        "status": "registered",
        "register_time": "2026-03-18T08:00:00Z"
      }
    ]
  }
}

注册到上级平台

POST /gb28181/cascade/register
Content-Type: application/json

{
  "platform_id": "34020000002000000001",
  "address": "10.0.0.100:5060",
  "transport": "TCP",
  "username": "34020000001320000001",
  "password": "password123",
  "expires": 3600
}

取消注册

POST /gb28181/cascade/{platform_id}/unregister

推送通道到上级

POST /gb28181/cascade/{platform_id}/push_channels
Content-Type: application/json

{
  "channel_ids": [
    "34020000001310000001",
    "34020000001310000002"
  ]
}

将本地通道信息推送到上级平台，使上级平台可以查看和控制这些通道。