GB28181 API

The GB28181 plugin provides a complete GB/T 28181 protocol API, supporting device access management, channel queries, PTZ control, recording query and playback, and cascade platform integration.

Enabling the Plugin

features = ["gb28181"]

Device Management

Query Device List

GET /gb28181/devices

Returns all registered GB/T 28181 devices.

Response example:

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 2,
    "devices": [
      {
        "device_id": "34020000001320000001",
        "name": "Front Door Camera",
        "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
      }
    ]
  }
}

Query Single Device

GET /gb28181/device/{device_id}

Returns detailed information for the specified device.

Delete Device

DELETE /gb28181/device/{device_id}

Remove the specified device from the system.

Response example:

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

Refresh Device Info

POST /gb28181/device/{device_id}/refresh

Send a Catalog query to the device to refresh device information and channel list.

Channel Management

Query Device Channels

GET /gb28181/device/{device_id}/channels

Returns all channels for the specified device.

Response example:

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

Live Preview (Invite)

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

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

Send an Invite request to the device to start live video preview. On success, the stream is published to the specified stream_path.

Parameter	Type	Description
`stream_path`	string	Stream publish path (optional, auto-generated by default)
`transport`	string	Transport method: `UDP` or `TCP` (default UDP)
`ssrc`	string	SSRC (optional, auto-assigned by default)

Response example:

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

Stop Preview (Bye)

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

Stop the live preview by sending a BYE request to the device.

PTZ Control

Send PTZ Command

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

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

Control the camera’s pan-tilt direction and lens zoom.

Command List

Command	Description
`up`	Pan up
`down`	Pan down
`left`	Pan left
`right`	Pan right
`upleft`	Pan upper-left
`upright`	Pan upper-right
`downleft`	Pan lower-left
`downright`	Pan lower-right
`zoomin`	Zoom in
`zoomout`	Zoom out
`focusnear`	Focus near
`focusfar`	Focus far
`irisin`	Iris open
`irisout`	Iris close
`stop`	Stop movement

Speed Parameters

Parameter	Range	Description
`speed`	1-255	Movement speed, 128 is medium
`priority`	0-15	Control priority, higher value means higher priority

PTZ Control Examples

Pan left:

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

Zoom in:

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

Stop:

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

Preset Control

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

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

Action	Description
`set`	Save current position as preset
`goto`	Move to specified preset
`remove`	Delete preset

Recording Query

Query Device Recordings

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
}

Parameter	Type	Description
`start_time`	RFC3339	Query start time
`end_time`	RFC3339	Query end time
`type`	string	Recording type: `all`, `alarm`, `manual`, `timer`
`page`	int	Page number
`page_size`	int	Items per page

Response example:

{
  "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
      }
    ]
  }
}

Recording Playback

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
}

Initiate a recording playback request. The device pushes recording data to the engine.

Parameter	Type	Description
`start_time`	RFC3339	Playback start time
`end_time`	RFC3339	Playback end time
`stream_path`	string	Playback stream path
`speed`	float	Playback speed (0.25 / 0.5 / 1.0 / 2.0 / 4.0)

Playback Control

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

{
  "action": "pause"
}

Action	Description
`pause`	Pause playback
`resume`	Resume playback
`speed`	Change playback speed (with `speed` parameter)
`seek`	Seek to specified time (with `position` parameter)
`stop`	Stop playback

Recording Download

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
}

Download device recordings to local storage at the specified playback speed.

Cascade Platform

Query Cascade Platforms

GET /gb28181/cascades

Returns information for all configured upstream platforms.

Response example:

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

Register with Upstream Platform

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
}

Unregister

POST /gb28181/cascade/{platform_id}/unregister

Push Channels to Upstream

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

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

Push local channel information to the upstream platform, allowing the upstream platform to view and control these channels.