第三方 API 分类速查
这一层只收录服务端到服务端的安全入口：长期 API Token 留在业务后端，浏览器和播放器只接收资源绑定的短时地址。接口按资源、直播、录像和裁剪删除分类。
本页覆盖 27 个接口。每一行都回答五件事：接口地址、它做什么、何时调用、如何确认完成、谁可以调用。参数字段的精确定义以同版本 OpenAPI 为准。
“业务接口”可以由 WebUI 或第三方系统按权限调用；“管理员接口”需要后台管理员；“内部接口/内部回调”只允许产品组件之间使用。
接入与资源
| 接口 | 讲人话 | 什么时候用 | 调完看什么 | 身份 / 权限 | 主要输入 |
|---|---|---|---|---|---|
GET /api/v2/third-party/capabilities |
验证第三方 API Token 并读取能力分类。 | 在展示功能、生成表单或发起控制前，先用它确认当前版本和目标设备真正支持什么。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 第三方接口<br>authenticated |
无业务参数 |
GET /api/v2/third-party/media-servers |
查询第三方可用媒体节点。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 第三方接口<br>nodes.view |
clusterId |
通道与直播
| 接口 | 讲人话 | 什么时候用 | 调完看什么 | 身份 / 权限 | 主要输入 |
|---|---|---|---|---|---|
GET /api/v2/third-party/channels |
分页查询第三方视频通道。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 第三方接口<br>channels.view |
page、pageSize、mediaServerId、nodeId、protocol、vhost、app、stream、streamId、deviceId、deviceChannelId、enabled、autoVideo、autoRecord、noPlayerBreak、hasAudio、hasPtz、isShareChannel、desiredState、actualState、sourceUrl、keyword |
GET /api/v2/third-party/channels/{channelId} |
查看第三方视频通道详情。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 第三方接口<br>channels.view |
channelId（必填） |
POST /api/v2/third-party/channels/{channelId}/playback |
签发第三方直播短时播放地址。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 第三方接口<br>streams.play |
channelId（必填）、ThirdPartyLivePlaybackRequest |
POST /api/v2/third-party/channels/{channelId}/playback-lease |
创建 URL 不变的第三方直播播放租约。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 第三方接口<br>streams.play |
channelId（必填）、ThirdPartyPlaybackLeaseRequest |
POST /api/v2/third-party/channels/{channelId}/start |
启动第三方视频通道拉流。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 第三方接口<br>channels.manage |
channelId（必填） |
POST /api/v2/third-party/channels/{channelId}/stop |
停止并暂停第三方视频通道。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 第三方接口<br>channels.manage |
channelId（必填） |
GET /api/v2/third-party/streams |
查询第三方流会话状态。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 第三方接口<br>streams.view |
mediaServerId、streamId、state |
裁剪合并
| 接口 | 讲人话 | 什么时候用 | 调完看什么 | 身份 / 权限 | 主要输入 |
|---|---|---|---|---|---|
GET /api/v2/third-party/cut-merge/tasks |
分页查询第三方裁剪合并任务。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 第三方接口<br>recordings.view |
mediaServerId、taskStatus、mainId、page、pageSize |
POST /api/v2/third-party/cut-merge/tasks |
创建第三方录像裁剪合并任务。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 第三方接口<br>recordings.manage |
CutMergeRequest |
DELETE /api/v2/third-party/cut-merge/tasks/{taskId} |
删除第三方裁剪合并任务。 | 用户明确确认删除或清理后调用；调用前应先展示影响范围。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 第三方接口<br>recordings.delete |
taskId（必填）、deleteOutputFile |
GET /api/v2/third-party/cut-merge/tasks/{taskId} |
查看第三方裁剪合并任务状态。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 第三方接口<br>recordings.view |
taskId（必填） |
POST /api/v2/third-party/cut-merge/tasks/{taskId}/download-link |
签发裁剪合并结果短时下载地址。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 第三方接口<br>recordings.download |
taskId（必填）、ThirdPartyMediaLinkRequest |
POST /api/v2/third-party/cut-merge/tasks/{taskId}/playback-lease |
创建 URL 不变的裁剪结果播放租约。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 第三方接口<br>recordings.play |
taskId（必填）、ThirdPartyPlaybackLeaseRequest |
POST /api/v2/third-party/cut-merge/tasks/{taskId}/playback-link |
签发裁剪合并结果短时播放地址。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 第三方接口<br>recordings.play |
taskId（必填）、ThirdPartyMediaLinkRequest |
国标录像回放
| 接口 | 讲人话 | 什么时候用 | 调完看什么 | 身份 / 权限 | 主要输入 |
|---|---|---|---|---|---|
POST /api/v2/third-party/gb28181/playback-sessions/{sessionId}/playback-lease |
为 GB28181 回放会话创建播放租约。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 第三方接口<br>streams.play |
sessionId（必填）、ThirdPartyPlaybackLeaseRequest |
播放租约
| 接口 | 讲人话 | 什么时候用 | 调完看什么 | 身份 / 权限 | 主要输入 |
|---|---|---|---|---|---|
DELETE /api/v2/third-party/playback-leases/{leaseId} |
撤销第三方播放会话。 | 用户明确确认删除或清理后调用；调用前应先展示影响范围。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 第三方接口<br>authenticated |
leaseId（必填）、reason |
GET /api/v2/third-party/playback-leases/{leaseId} |
查询第三方可续租播放会话状态。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 第三方接口<br>authenticated |
leaseId（必填） |
POST /api/v2/third-party/playback-leases/{leaseId}/renew |
续租第三方播放会话且保持 URL 不变。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 第三方接口<br>authenticated |
leaseId（必填）、RenewThirdPartyPlaybackLeaseRequest |
录像与删除
| 接口 | 讲人话 | 什么时候用 | 调完看什么 | 身份 / 权限 | 主要输入 |
|---|---|---|---|---|---|
GET /api/v2/third-party/recordings |
分页查询第三方录像文件。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 第三方接口<br>recordings.view |
page、pageSize、channelId、mediaServerId、nodeId、app、streamId、fileState、startTime、endTime |
POST /api/v2/third-party/recordings/{fileId}/download-link |
签发录像短时下载地址。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 第三方接口<br>recordings.download |
fileId（必填）、ThirdPartyMediaLinkRequest |
POST /api/v2/third-party/recordings/{fileId}/playback-lease |
创建 URL 不变的录像播放租约。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 第三方接口<br>recordings.play |
fileId（必填）、ThirdPartyPlaybackLeaseRequest |
POST /api/v2/third-party/recordings/{fileId}/playback-link |
签发录像短时播放地址。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 第三方接口<br>recordings.play |
fileId（必填）、ThirdPartyMediaLinkRequest |
POST /api/v2/third-party/recordings/hard-delete |
第三方批量发起录像硬删除。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 第三方接口<br>recordings.delete |
RecordFileBatchRequest |
POST /api/v2/third-party/recordings/restore |
第三方批量恢复软删除录像。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 第三方接口<br>recordings.manage |
RecordFileBatchRequest |
POST /api/v2/third-party/recordings/soft-delete |
第三方批量软删除录像。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 第三方接口<br>recordings.delete |
RecordFileBatchRequest |
接口字段与示例
本页故意先讲清业务用途，不把几百个字段塞进说明文字。真正编码时，请使用与部署版本一起提供的 OpenAPI 和 Postman 资产查看请求体、响应体、枚举、文件类型与示例；不要拿网站最新契约调用旧版本服务。
