Third-party API: live playback

Live integration has three steps: find the channel, make sure media is truly online, and issue short-lived URLs for the current player. Do not build a playback URL as soon as an API says that a command was accepted.

sequenceDiagram
    participant Backend as Business backend
    participant API as AKStream.Next
    participant Device as Camera or GB device
    participant Media as MediaServer
    Backend->>API: Query safe channel view
    opt Stream is offline and control is allowed
        Backend->>API: Start channel or send GB28181 INVITE
        API->>Device: Pull or request live media
        Device->>Media: Publish media
    end
    Backend->>API: Query stream state
    API-->>Backend: Online
    Backend->>API: Request short playback URLs
    API-->>Backend: HLS/FLV/fMP4 URLs

Query and start a channel

Read one channel:

GET /api/v2/third-party/channels/{channelId}
Authorization: Bearer ak_pat_<TOKEN>

For a regular RTSP/ONVIF channel:

POST /api/v2/third-party/channels/{channelId}/start
Authorization: Bearer ak_pat_<TOKEN>

GB28181 live view needs the SIP INVITE, RTP port, and SSRC state machine, so use the native endpoint:

POST /api/v2/gb28181/live/invite
Authorization: Bearer ak_pat_<TOKEN>
Content-Type: application/json

{
  "deviceId": "34020000001320000001",
  "channelId": "34020000001320000002",
  "mediaServerId": "zlm-prod-01",
  "rtpWithTcp": false,
  "timeoutSeconds": 30
}

Starting a regular channel requires channels.manage; GB28181 live view requires devices.control. Both requests only accept work. Query the resulting stream:

GET /api/v2/third-party/streams?mediaServerId=zlm-prod-01&streamId=camera-001&state=Online
Authorization: Bearer ak_pat_<TOKEN>

GB28181 device recordings

GET /api/v2/gb28181/records/query/{taskId} returns device-side RecordInfo metadata. A device file:///, FilePath, or Address is an opaque locator, not a browser URL. The safe response hides those values and provides a playback action for every valid record:

1. Call POST /api/v2/gb28181/playback/invite with playback.request.
2. Keep the returned session.id and wait until its app/stream is Online.
3. Call POST /api/v2/third-party/gb28181/playback-sessions/{sessionId}/playback-lease.
4. Play a returned HTTP-FLV, HTTP-fMP4, or HLS source and renew at renewAfter.

Listing device records requires devices.view, Playback INVITE requires devices.control, and Web playback leases require streams.play.

Request playback URLs

After the stream becomes Online, create a playback lease whose URLs remain stable:

POST /api/v2/third-party/channels/{channelId}/playback-lease
Authorization: Bearer ak_pat_<TOKEN>
Content-Type: application/json

{
  "protocols": ["http-flv", "http-fmp4", "hls"],
  "leaseSeconds": 120,
  "absoluteLifetimeSeconds": 43200
}

Example response:

{
  "leaseId": "01234567-89ab-cdef-0123-456789abcdef",
  "resourceKind": "live",
  "resourceId": "camera-001",
  "state": "Active",
  "createdAt": "2026-08-24T10:00:00Z",
  "expiresAt": "2026-08-24T10:02:00Z",
  "renewAfter": "2026-08-24T10:01:24Z",
  "absoluteExpiresAt": "2026-08-24T22:00:00Z",
  "sources": [
    {
      "protocol": "http-flv",
      "url": "https://media.example.com/live/camera-001-main.live.flv?ak_ticket=<short-ticket>",
      "contentType": "video/x-flv",
      "browserNative": false,
      "hint": "Use flv.js in a browser; H.265 is usually incompatible."
    }
  ]
}

Renewal, stopping, and errors

The sliding lease lasts 60—600 seconds and defaults to 120 seconds. Absolute lifetime is at most 12 hours and never exceeds the original API token's expiry. The server normally places renewAfter at about 70% of the current lease; clients must use the returned value instead of calculating it. At that time, the backend calls:

POST /api/v2/third-party/playback-leases/{leaseId}/renew
Authorization: Bearer ak_pat_<TOKEN>
Content-Type: application/json

{"leaseSeconds":120}

Renewal returns no new URL and does not change the existing ak_ticket. HTTP-FLV and HTTP-fMP4 are single long-lived connections, so a new URL cannot and need not be injected. HLS keeps the same URL and MediaServer cookie. After a disconnect, reconnect with the same URL as long as the lease was renewed. An expired lease cannot be revived; create a new one.

Revoke with DELETE /api/v2/third-party/playback-leases/{leaseId}. Revocation denies new connections but does not forcibly kick an established player by default. The original /playback endpoint remains compatible for short non-renewable use.

Stop a regular channel:

POST /api/v2/third-party/channels/{channelId}/stop
Authorization: Bearer ak_pat_<TOKEN>

Use /api/v2/gb28181/live/stop for a GB28181 stream. If automatic live recovery is enabled, pause that policy as required before sending BYE, or the device may be invited again.

Production acceptance must also cover HTTPS mixed content, CORS, reverse-proxy buffering, and long-connection timeouts. The API host is not necessarily the media host.