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

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

## 查询、播放和下载

按通道和时间查询录像：

```http
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 不变的播放租约：

```http
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`，两种凭据不能互换，下载链接不可续租。

## 开始和停止录像

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

```http
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` 中出现可用文件为准。

## 裁剪和合并

创建任务：

```http
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`，避免旧回调把物理路径外发到任意地址。请查询：

```http
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}` | 默认同时删除任务输出文件，不返回服务器路径 |

批量请求格式：

```json
{
  "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`。删除前应在你自己的页面明确展示文件数量、时间范围和不可恢复影响。