第三方 API：录像、裁剪和删除

录像文件只能通过 fileId 操作。第三方接口不会返回服务器物理路径、原始 Hook JSON 或节点删除命令载荷。

查询、播放和下载

按通道和时间查询录像：

GET /api/v2/third-party/recordings?channelId=camera-001&startTime=2026-08-24T08:00:00%2B08:00&endTime=2026-08-24T10:00:00%2B08:00&page=1&pageSize=50
Authorization: Bearer ak_pat_<TOKEN>

startTime/endTime 使用时间交集：录像只要与查询窗口有重叠就会返回。用 fileState=Available 只查可播放文件。

查询结果不会出现服务器 FilePath 或 file:///。每行会给出 playbackLinkEndpoint、playbackLeaseEndpoint 和 downloadLinkEndpoint；它们是下一步 POST 接口，不是已经签发的播放票据。需要播放时优先调用该行的 playbackLeaseEndpoint。

长录像或原生 <video> 播放推荐创建 URL 不变的播放租约：

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

{"leaseSeconds":120,"absoluteLifetimeSeconds":43200}

到 renewAfter 时调用 /api/v2/third-party/playback-leases/{leaseId}/renew。续租只更新时间，URL 不变，因此浏览器后续 Range 请求不需要重设 video.src 或恢复 currentTime。不需要续租的短播放仍可使用 /playback-link；下载使用 /download-link。播放要求 recordings.play，下载要求 recordings.download，两种凭据不能互换，下载链接不可续租。

开始和停止录像

手工开始录像继续使用领域接口：

POST /api/v2/recording/start
Authorization: Bearer ak_pat_<TOKEN>
Content-Type: application/json

{
  "channelId": "camera-001",
  "mediaServerId": "zlm-prod-01",
  "app": "live",
  "streamId": "camera-001-main",
  "vhost": "__defaultVhost__",
  "recordSource": "Manual"
}

停止时调用 /api/v2/recording/stop，然后查询 /api/v2/recording/sessions。命令成功不等于 MP4 已经封口；最终以录像会话终态、WebHook 和 /third-party/recordings 中出现可用文件为准。

裁剪和合并

创建任务：

POST /api/v2/third-party/cut-merge/tasks
Authorization: Bearer ak_pat_<TOKEN>
Content-Type: application/json

{
  "channelId": "camera-001",
  "mainId": "camera-001",
  "app": "live",
  "vhost": "__defaultVhost__",
  "startTime": "2026-08-24T08:15:00+08:00",
  "endTime": "2026-08-24T08:35:00+08:00"
}

第三方入口不接受 callbackUrl，避免旧回调把物理路径外发到任意地址。请查询：

GET /api/v2/third-party/cut-merge/tasks/{taskId}
Authorization: Bearer ak_pat_<TOKEN>

等 taskStatus=Closed 后，长时间播放使用 /playback-lease，短播放或下载使用 /playback-link、/download-link。一次任务最长 120 分钟；所选录像跨多个物理节点时会明确拒绝，需要缩小时间范围或先归档到同一节点。

平台录像与裁剪任务的普通查询同样只返回 /media、/download 等 HTTP 入口，不返回物理路径、原始 Hook/计划 JSON、回调地址或内部命令编号。

软删、恢复和硬删

动作	接口	实际效果
软删除	`POST /api/v2/third-party/recordings/soft-delete`	隐藏录像并开始可恢复窗口，不删磁盘文件
恢复	`POST /api/v2/third-party/recordings/restore`	只恢复仍可撤销且物理文件可确认存在的录像
硬删除	`POST /api/v2/third-party/recordings/hard-delete`	创建可审计的节点删除命令；响应成功不等于物理文件已删
删除裁剪结果	`DELETE /api/v2/third-party/cut-merge/tasks/{taskId}`	默认同时删除任务输出文件，不返回服务器路径

批量请求格式：

{
  "fileIds": [
    "01234567-89ab-cdef-0123-456789abcdef",
    "11234567-89ab-cdef-0123-456789abcdef"
  ]
}

单次最多 200 个 ID。响应中的 succeeded 表示本阶段成功，failed 给出逐项原因。硬删除要继续查询录像状态或关联节点命令，直到 FileState=Deleted；不要因为 HTTP 200 就从自己的业务库永久抹掉记录。

常见状态和处理

状态	说明	建议动作
`Available`	文件可播放/下载	可以申请短时地址
`SoftDeleted`	已软删，可能仍可恢复	查看 `canUndoDelete/deleteUndoUntil`
`DeleteRequested`	节点硬删除命令已创建	等命令回写，不重复提交
`Deleted`	物理删除流程已完成	保留业务审计，停止播放和下载
`Missing`	索引存在但磁盘文件找不到	检查挂载、节点和扫描结果
`DeleteFailed`	删除命令或文件操作失败	保存 TraceId 和失败原因，修复后再重试
播放返回“当前节点不可访问”	录像在远端节点且当前实例没有共享挂载	把请求路由到文件所属节点，或部署共享受管录像根目录

软删、硬删和删除裁剪结果需要 recordings.delete；恢复、开始/停止录像和裁剪合并需要 recordings.manage。删除前应在你自己的页面明确展示文件数量、时间范围和不可恢复影响。