Skip to content

Skill references guides development third party recording

Jump to bottom
AKStream documentation edited this page Oct 28, 2026 · 2 revisions

第三方 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 只查可播放文件。

按多个字段排序

GET /api/v2/recording/files 和 GET /api/v2/third-party/recordings 均支持可选参数 sort：

GET /api/v2/third-party/recordings?channelId=camera-001&page=1&pageSize=50&sort=startedAt:desc,sizeBytes:asc
Authorization: Bearer ak_pat_<TOKEN>

先按录像开始时间倒序，再对开始时间相同的文件按大小升序。排序作用于全部符合筛选条件的记录，然后分页。前端可用 URLSearchParams.set('sort', 'startedAt:desc,sizeBytes:asc') 编码参数。

  • 逗号分隔字段，从左到右依次降低优先级；各字段独立使用 asc 或 desc，省略方向时为 asc。
  • 字段名和方向不区分大小写，允许两侧空格。
  • 不传、空串或纯空白时，默认 createdAt:desc；这是索引创建时间，不等于录像开始时间。
  • 空值始终排在该字段的非空值后；未指定 id/fileId 时自动追加 id:asc，固定同值记录的顺序。
  • 非法字段、非法方向、重复字段（包括同时使用 id 和 fileId）、空排序项返回 HTTP 400；第三方错误码为 recording_query_invalid。不接受 SQL 表达式。
  • 每个字段最多使用一次，sort 总长度不超过 2048 字符。
两个接口共有的可排序字段 含义
id、fileId 同一文件唯一编号的两个名称，任选其一
channelId、nodeId、mediaServerId 通道、节点、媒体服务器编号
vhost、app、streamId 流路由字段
fileName、recordDate 文件名、录像日期
sizeBytes、durationSeconds 文件字节数、时长（秒）
fileState、canUndoDelete、deleteUndoUntil 文件状态、是否可恢复、恢复截止时间
existsOnDisk 最近扫描是否存在
startedAt、endedAt 录像开始、结束时间
createdAt、updatedAt 索引创建、更新时间

/api/v2/recording/files 另支持其响应中的 sourceHook、indexSource、deletedAt、lastScannedAt；第三方接口不接受这四个字段。媒体 URL、下载 URL、服务器物理路径和内部载荷不参与排序。

文本按数据库配置的排序规则比较。同值顺序确定不等于数据快照：翻页期间新增、修改或删除记录仍可能改变结果集合。此能力需要服务端包含该更新，旧安装包不因文档更新而自动支持。

查询结果不会出现服务器 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。删除前应在你自己的页面明确展示文件数量、时间范围和不可恢复影响。

AKStream.Next 官网 / Official website · Releases · 中文 · English

首页 / Home

Clone this wiki locally