录像、文件、裁剪与磁盘接口
这一层覆盖录像计划、手工录像、文件检索、在线播放、下载、软删除、恢复、裁剪合并和磁盘治理。创建任务只代表进入队列，成品是否可用必须继续查询任务和文件状态。
本页覆盖 56 个接口。每一行都回答五件事：接口地址、它做什么、何时调用、如何确认完成、谁可以调用。参数字段的精确定义以同版本 OpenAPI 为准。
“业务接口”可以由 WebUI 或第三方系统按权限调用；“管理员接口”需要后台管理员；“内部接口/内部回调”只允许产品组件之间使用。
录像计划
| 接口 | 讲人话 | 什么时候用 | 调完看什么 | 身份 / 权限 | 主要输入 |
|---|---|---|---|---|---|
GET /api/v2/recording/plans |
查询录像计划列表。 | 准备执行变更前先调用，用来预览影响范围，确认无误后再调用真正执行接口。 | 返回的是计划或评估结果，不会自动执行真正变更。 | 业务接口<br>recordings.view |
name |
POST /api/v2/recording/plans |
创建录像计划。 | 准备执行变更前先调用，用来预览影响范围，确认无误后再调用真正执行接口。 | 返回的是计划或评估结果，不会自动执行真正变更。 | 业务接口<br>recordings.manage |
SaveRecordPlanRequest |
DELETE /api/v2/recording/plans/{planId} |
删除录像计划。 | 准备执行变更前先调用，用来预览影响范围，确认无误后再调用真正执行接口。 | 返回的是计划或评估结果，不会自动执行真正变更。 | 业务接口<br>recordings.delete |
planId（必填） |
GET /api/v2/recording/plans/{planId} |
查看录像计划。 | 准备执行变更前先调用，用来预览影响范围，确认无误后再调用真正执行接口。 | 返回的是计划或评估结果，不会自动执行真正变更。 | 业务接口<br>recordings.view |
planId（必填） |
PUT /api/v2/recording/plans/{planId} |
更新录像计划。 | 准备执行变更前先调用，用来预览影响范围，确认无误后再调用真正执行接口。 | 返回的是计划或评估结果，不会自动执行真正变更。 | 业务接口<br>recordings.manage |
planId（必填）、SaveRecordPlanRequest |
POST /api/v2/recording/plans/{planId}/enabled |
启用或停用录像计划。 | 准备执行变更前先调用，用来预览影响范围，确认无误后再调用真正执行接口。 | 返回的是计划或评估结果，不会自动执行真正变更。 | 业务接口<br>recordings.manage |
planId（必填）、enabled（必填） |
GET /api/v2/recording/plans/{planId}/evaluate |
判断指定时间是否命中录像计划。 | 准备执行变更前先调用，用来预览影响范围，确认无误后再调用真正执行接口。 | 返回的是计划或评估结果，不会自动执行真正变更。 | 业务接口<br>recordings.view |
planId（必填）、at |
录像与磁盘
| 接口 | 讲人话 | 什么时候用 | 调完看什么 | 身份 / 权限 | 主要输入 |
|---|---|---|---|---|---|
POST /api/v2/recording/auto-record/evaluate-stream |
只评估指定流媒体服务流对应的自动录像计划。 | 准备执行变更前先调用，用来预览影响范围，确认无误后再调用真正执行接口。 | 返回的是计划或评估结果，不会自动执行真正变更。 | 业务接口<br>recordings.manage |
mediaServerId（必填）、vhost、app（必填）、streamId（必填）、at |
POST /api/v2/recording/auto-record/run-once |
立即执行一次自动录像计划调度。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>recordings.manage |
at |
GET /api/v2/recording/plan-template |
查看录像计划模板示例。 | 准备执行变更前先调用，用来预览影响范围，确认无误后再调用真正执行接口。 | 返回的是计划或评估结果，不会自动执行真正变更。 | 业务接口<br>recordings.view |
无业务参数 |
GET /api/v2/recording/search/capabilities |
探测当前节点 CPU、CUDA、RKNN、MPS 运行时及模型验收状态。 | 在展示功能、生成表单或发起控制前，先用它确认当前版本和目标设备真正支持什么。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>system.config.view |
无业务参数 |
GET /api/v2/recording/search/dependencies |
06 录像与磁盘：GET /api/v2/recording/search/dependencies。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>recordings.play |
无业务参数 |
POST /api/v2/recording/search/dependencies |
06 录像与磁盘：POST /api/v2/recording/search/dependencies。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>recordings.play |
DependencyDownloadRequest |
POST /api/v2/recording/search/dependencies/cancel |
06 录像与磁盘：POST /api/v2/recording/search/dependencies/cancel。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>recordings.play |
无业务参数 |
GET /api/v2/recording/search/hardware |
查看当前节点 SoC、NPU 核心数与 FFmpeg 硬件加速能力。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>system.config.view |
无业务参数 |
POST /api/v2/recording/search/image |
以图片检索已勾选通道的录像片段。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>recordings.play |
无业务参数 |
POST /api/v2/recording/search/index-jobs |
管理员在临时启用文件补救后，按录像 ID 手工提交有界补建任务。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>recordings.manage |
RecordingFileRecoveryRequest |
POST /api/v2/recording/search/prepare |
在后台加载、编译缓存并预热当前所选图文模型。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>recordings.play |
无业务参数 |
GET /api/v2/recording/search/status |
查询录像图文检索的授权、通道范围、直播采样和文件补救运行态。 | 做页面概览、运行监控或排障时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>recordings.play |
无业务参数 |
POST /api/v2/recording/search/text |
以中文文字检索已勾选通道的录像片段。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>recordings.play |
RecordingSearchQueryRequest |
GET /api/v2/recording/sessions |
分页查询录像会话。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>recordings.view |
page、pageSize、mediaServerId、nodeId、channelId、app、streamId、state、recordSource |
POST /api/v2/recording/start |
创建开始录像命令。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>recordings.manage |
StartRecordingRequest |
GET /api/v2/recording/state-model |
查看录像状态机说明。 | 在展示功能、生成表单或发起控制前，先用它确认当前版本和目标设备真正支持什么。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>recordings.view |
无业务参数 |
POST /api/v2/recording/stop |
创建停止录像命令。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>recordings.manage |
StopRecordingRequest |
录像文件
| 接口 | 讲人话 | 什么时候用 | 调完看什么 | 身份 / 权限 | 主要输入 |
|---|---|---|---|---|---|
GET /api/v2/recording/files |
分页查询录像文件索引。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>recordings.view |
page、pageSize、mediaServerId、nodeId、channelId、app、streamId、fileState、recordDate、sourceHook、indexSource、startTime、endTime |
GET /api/v2/recording/files/{fileId}/download |
下载录像文件。 | 页面加载、刷新状态或按条件检索数据时调用。 | 检查 Content-Type、文件长度或 Range 响应，不要按普通 JSON 解析。 | 业务接口<br>recordings.download |
fileId（必填） |
GET /api/v2/recording/files/{fileId}/media |
播放录像文件。 | 页面加载、刷新状态或按条件检索数据时调用。 | 检查 Content-Type、文件长度或 Range 响应，不要按普通 JSON 解析。 | 业务接口<br>recordings.play |
fileId（必填） |
POST /api/v2/recording/files/delete |
发起录像文件硬删除请求。 | 用户明确确认删除或清理后调用；调用前应先展示影响范围。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>recordings.delete |
DeleteRecordFilesRequest |
POST /api/v2/recording/files/restore |
恢复软删除录像文件。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>recordings.manage |
RecordFileBatchRequest |
POST /api/v2/recording/files/scan |
扫描录像目录并补偿录像文件索引。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>recordings.manage |
RecordFileScanRequest |
POST /api/v2/recording/files/soft-delete |
软删除录像文件，保留可恢复窗口。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>recordings.delete |
RecordFileBatchRequest |
GET /api/v2/recording/files/statistics |
统计通道全部有效录像资产。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>recordings.view |
channelId |
磁盘与存储
| 接口 | 讲人话 | 什么时候用 | 调完看什么 | 身份 / 权限 | 主要输入 |
|---|---|---|---|---|---|
GET /api/v2/recording/disk-check-template |
查看磁盘保障检查项。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>recordings.view |
无业务参数 |
POST /api/v2/recording/disk/browser/directories |
在当前磁盘位置新建并验证录像目录。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>recordings.manage |
RecordRootDirectoryCreateRequest |
POST /api/v2/recording/disk/browser/entries |
浏览服务器上的录像目录候选项。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>recordings.manage |
RecordRootDirectoryBrowseRequest |
POST /api/v2/recording/disk/browser/roots |
列出录像管理员可选择的服务器目录入口。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>recordings.manage |
无业务参数 |
POST /api/v2/recording/disk/check |
立即执行一次录像磁盘检查。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>recordings.manage |
无业务参数 |
GET /api/v2/recording/disk/fallback-recovery |
查询当前节点的掉盘录像预检与恢复任务。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>recordings.view |
limit |
POST /api/v2/recording/disk/fallback-recovery/preview |
创建掉盘录像预检任务。 | 准备执行变更前先调用，用来预览影响范围，确认无误后再调用真正执行接口。 | 返回的是计划或评估结果，不会自动执行真正变更。 | 业务接口<br>recordings.manage |
RecordRootFallbackRecoveryRequest |
POST /api/v2/recording/disk/fallback-recovery/run |
创建掉盘录像正式恢复任务。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>recordings.manage |
RecordRootFallbackRecoveryRequest |
POST /api/v2/recording/disk/guard |
立即执行一次录像磁盘检查并应用暂停/恢复守护。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>recordings.manage |
无业务参数 |
GET /api/v2/recording/disk/identities |
查询当前节点已经由管理员验证并绑定的录像硬盘身份。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>recordings.view |
无业务参数 |
POST /api/v2/recording/disk/probe-root |
只读探测录像根目录所属硬盘及容量信息。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>recordings.manage |
RecordRootIdentityInspectRequest |
GET /api/v2/recording/disk/roots |
查看当前配置下的录像根目录。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>recordings.view |
无业务参数 |
GET /api/v2/recording/disk/states |
查询磁盘卷状态。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>recordings.view |
无业务参数 |
POST /api/v2/recording/disk/validate-root |
验证录像目录并在首次成功时绑定当前硬盘身份。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>recordings.manage |
RecordRootIdentityBindRequest |
裁剪与合并
| 接口 | 讲人话 | 什么时候用 | 调完看什么 | 身份 / 权限 | 主要输入 |
|---|---|---|---|---|---|
GET /api/v2/recording/cut-merge/backlog |
查询录像裁剪/合并积压任务。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>recordings.view |
mediaServerId（必填） |
POST /api/v2/recording/cut-merge/cleanup |
清理裁剪合并临时目录和按保留策略清理输出文件。 | 用户明确确认删除或清理后调用；调用前应先展示影响范围。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>recordings.manage |
CutMergeCleanupRequest |
GET /api/v2/recording/cut-merge/tasks |
查询录像裁剪/合并任务列表。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>recordings.view |
mediaServerId、taskStatus、mainId、app、page、pageSize |
POST /api/v2/recording/cut-merge/tasks |
创建录像裁剪/合并任务。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>recordings.manage |
CutMergeRequest |
DELETE /api/v2/recording/cut-merge/tasks/{taskId} |
真删除录像裁剪/合并任务和输出文件。 | 用户明确确认删除或清理后调用；调用前应先展示影响范围。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>recordings.delete |
taskId（必填）、deleteOutputFile |
GET /api/v2/recording/cut-merge/tasks/{taskId} |
查询录像裁剪/合并任务状态。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>recordings.view |
taskId（必填）、mediaServerId（必填） |
GET /api/v2/recording/cut-merge/tasks/{taskId}/detail |
查询录像裁剪/合并任务安全详情。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>recordings.view |
taskId（必填）、mediaServerId |
GET /api/v2/recording/cut-merge/tasks/{taskId}/download |
下载裁剪合并输出文件。 | 页面加载、刷新状态或按条件检索数据时调用。 | 检查 Content-Type、文件长度或 Range 响应，不要按普通 JSON 解析。 | 业务接口<br>recordings.download |
taskId（必填） |
GET /api/v2/recording/cut-merge/tasks/{taskId}/media |
播放裁剪合并输出文件。 | 页面加载、刷新状态或按条件检索数据时调用。 | 检查 Content-Type、文件长度或 Range 响应，不要按普通 JSON 解析。 | 业务接口<br>recordings.play |
taskId（必填） |
GET /api/v2/recording/cut-merge/tasks/{taskId}/status |
查询录像裁剪/合并任务状态。 | 做页面概览、运行监控或排障时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>recordings.view |
taskId（必填）、mediaServerId（必填） |
接口字段与示例
本页故意先讲清业务用途，不把几百个字段塞进说明文字。真正编码时，请使用与部署版本一起提供的 OpenAPI 和 Postman 资产查看请求体、响应体、枚举、文件类型与示例；不要拿网站最新契约调用旧版本服务。
