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

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

```http
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 对接](api-rtc.md)和[档案对接](api-rtc-archive.md)。