第三方业务 API：27 个接口怎么接

这 27 个入口用于业务后端到 AKStream.Next；前端只拿获准资源的短时播放/下载地址。参数以目标版本的公开契约为准。请求头 Authorization: Bearer ak_pat_... 必须是独立、限权的业务 API Token；先调 GET /api/v2/third-party/capabilities 验证版本与权限。所有时间按 UTC 传入或按响应时区解析，任务型接口应查询终态，不能把 HTTP 200 当作摄像机已上线或文件已生成。

POST /api/v2/third-party/channels/{channelId}/playback
Authorization: Bearer <业务后端 API Token>
Content-Type: application/json

{"protocols":["hls","http-flv"],"lifetimeSeconds":120}

响应的 sources[] 是短时播放地址，expiresAt 是到期时间；只为已 Online 的真实通道签发，调用不会暗中启动离线通道。业务后端判断当前用户有权看哪条通道后，才把地址交给播放器。

连接、通道与在线流

接口 权限 入参 返回与特殊情况
GET /api/v2/third-party/capabilities 有效 API Token 无 能力分类与支持范围；先用它核对当前部署，不靠文档猜功能。
GET /api/v2/third-party/media-servers nodes.view 可选 clusterId 可见媒体节点；节点在线不等于某通道在线。
GET /api/v2/third-party/channels channels.view page/pageSize、keyword、protocol、设备/节点/媒体节点、期望/实际状态等过滤 {page,pageSize,total,rows[]}；统一 channelId 是后续稳定引用。
GET /api/v2/third-party/channels/{channelId} channels.view 路由 channelId 通道状态、协议、媒体归属等；不向前端返回源地址中的账号密码。
POST /api/v2/third-party/channels/{channelId}/start channels.manage 路由 channelId {channel,command}；命令受理后继续查询通道/命令状态，不能将受理当已上线。
POST /api/v2/third-party/channels/{channelId}/stop channels.manage 路由 channelId streamCommandId/nodeCommandId/state；停用可影响其他正在观看该通道的业务。
GET /api/v2/third-party/streams streams.view mediaServerId、streamId、state 当前流会话；通道配置存在不代表有活动媒体。
POST /api/v2/third-party/channels/{channelId}/playback streams.play ThirdPartyLivePlaybackRequest channelId/mediaServerId/vhost/app/streamId/streamState/expiresAt/sources[]；只对在线流发短地址。
POST /api/v2/third-party/channels/{channelId}/playback-lease streams.play ThirdPartyPlaybackLeaseRequest leaseId、稳定 sources[]、续租时间；适合播放器 URL 不变的长观看。

GET /channels 支持 mediaServerId/nodeId/deviceId/deviceChannelId/vhost/app/stream/streamId/enabled/autoVideo/autoRecord/noPlayerBreak/hasAudio/hasPtz/isShareChannel/desiredState/actualState/sourceUrl/keyword 等过滤；不要把 sourceUrl 当作客户端播放地址。具体字段类型、可空性和响应对象见本版 OpenAPI。

录像文件、下载与删除

接口 权限 入参 返回与特殊情况
GET /api/v2/third-party/recordings recordings.view page/pageSize、channelId、节点/媒体节点、app/streamId/fileState/startTime/endTime {page,pageSize,total,rows[]}；仅返回调用者获准的文件，不提供服务器物理路径。
POST /api/v2/third-party/recordings/{fileId}/playback-link recordings.play 文件 ID、ThirdPartyMediaLinkRequest url/expiresAt/supportsRange；适合短时单次播放。
POST /api/v2/third-party/recordings/{fileId}/download-link recordings.download 同上 仅文件下载地址；播放权限不自动等于下载权限。
POST /api/v2/third-party/recordings/{fileId}/playback-lease recordings.play ThirdPartyPlaybackLeaseRequest URL 不变、按租期续租；原文件被删除或收权后租约也不可用。
POST /api/v2/third-party/recordings/soft-delete recordings.delete RecordFileBatchRequest.fileIds[] succeeded[]/failed[]；逐项处理失败，先软删再允许恢复。
POST /api/v2/third-party/recordings/restore recordings.manage 同上 批量恢复软删除；物理文件已清理时不能凭索引恢复字节。
POST /api/v2/third-party/recordings/hard-delete recordings.delete 同上 不可逆地移除可删文件；业务 UI 必须二次确认并展示逐项失败。

录像查询时间范围用于筛选与该范围有交集的文件；跨录像文件连续回放或导出一段指定时间，请用下面的裁剪合并任务，而不是自行拼接服务器路径。

裁剪合并任务

接口 权限 入参 返回与特殊情况
GET /api/v2/third-party/cut-merge/tasks recordings.view page/pageSize、mediaServerId/taskStatus/mainId 任务分页与运行状态。
POST /api/v2/third-party/cut-merge/tasks recordings.manage CutMergeRequest 的起止时间、稳定 channelId 或流定位，可选 callbackUrl taskId/taskStatus/processPercentage；创建成功后继续查状态；中间无录像的时间可跳过。
GET /api/v2/third-party/cut-merge/tasks/{taskId} recordings.view 任务 ID 进度、大小、实际时长、错误和完成时间；成功状态才签播放/下载。
DELETE /api/v2/third-party/cut-merge/tasks/{taskId} recordings.delete 任务 ID，可选 deleteOutputFile 删除任务；是否同时删结果文件由参数决定。
POST /api/v2/third-party/cut-merge/tasks/{taskId}/playback-link recordings.play 任务 ID、ThirdPartyMediaLinkRequest 短时播放地址；任务未完成时不可用。
POST /api/v2/third-party/cut-merge/tasks/{taskId}/download-link recordings.download 任务 ID、ThirdPartyMediaLinkRequest 短时下载地址；播放权限不能代替下载权限。
POST /api/v2/third-party/cut-merge/tasks/{taskId}/playback-lease recordings.play ThirdPartyPlaybackLeaseRequest 可续租的稳定结果地址。

CutMergeRequest 的 startTime/endTime 必须形成有效区间；channelId 优先作跨 MediaServer 稳定归属，mediaServerId 只是无法从命中文件定位执行节点时的兼容回退。callbackUrl 留空时主动查询；提供时必须是合法 URL，仍应以任务查询结果核对终态。

播放租约与国标回放

接口 权限 入参 返回与特殊情况
GET /api/v2/third-party/playback-leases/{leaseId} 同一 API Token + 原资源权限 租约 ID state/expiresAt/renewAfter/absoluteExpiresAt/renewCount；不允许别的 Token 接管。
POST /api/v2/third-party/playback-leases/{leaseId}/renew 同上 可选新 leaseSeconds URL 保持不变、滑动到期更新；不能超过绝对寿命。
DELETE /api/v2/third-party/playback-leases/{leaseId} 同上 租约 ID、可选 reason 主动撤销后原地址失效。
POST /api/v2/third-party/gb28181/playback-sessions/{sessionId}/playback-lease streams.play 已上线的国标回放会话 ID、租约参数 给该回放会话稳定播放地址；先确保 Playback INVITE 已建立。

租约响应 leaseId 用于查询、续租、撤销；resourceKind 为 live/recording-file/cut-merge-output；sources[] 是创建时返回的稳定地址。renewAfter 是建议续租时间，expiresAt 是当前滑动到期，absoluteExpiresAt 是硬截止。播放器保留 URL，业务后端按建议时间续租；播放被收权后不能靠续租继续观看。

常用请求与响应字段

模型/字段 类型和作用 默认/约束
ThirdPartyLivePlaybackRequest.protocols string[]，http-flv/http-fmp4/hls 省略返回全部三种；目标必须在线。
ThirdPartyLivePlaybackRequest.lifetimeSeconds 短地址秒数 默认120；至少30，最大受服务配置限制。
ThirdPartyPlaybackLeaseRequest.leaseSeconds 滑动租期秒数 60–600，默认120。
ThirdPartyPlaybackLeaseRequest.absoluteLifetimeSeconds 不可续过的总寿命秒数 不短于租期，最多43200（12小时）。
ThirdPartyMediaLinkRequest.lifetimeSeconds 单次播放/下载地址秒数 默认120。
RenewThirdPartyPlaybackLeaseRequest.leaseSeconds 本次续租的滑动秒数 60–600；省略沿用创建时设置。
RecordFileBatchRequest.fileIds 待处理文件 ID 数组 每项独立返回成功或失败。
ThirdPartyMediaLink resourceKind/resourceId/action/url/expiresAt/supportsRange url 是受控 HTTP 地址，不是 file:// 或服务端目录。

典型错误：401 是 Token 无效/撤销，403 是权限或资源范围不足，404 是通道/文件/任务不存在或不可见，409 常表示目标未上线或状态冲突，429 表示速率限制。不要对 403/404 无界重试；任务提交后的结果未知时先按任务 ID 查询，避免重复创建。RTC 专项 API 见RTC 对接和档案对接。

完整 Skill 文件目录