# 第三方 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 资产查看请求体、响应体、枚举、文件类型与示例；不要拿网站最新契约调用旧版本服务。