01文档说明#
1.1适用范围与读者
本页面向需要与 PowerMedia 智能媒体服务器进行系统集成或二次开发的技术人员,覆盖以下读者:
- 集成方开发人员:需要调用上传、查询、播放授权、分享与任务类接口完成业务系统对接。
- 实施与运维人员:需要了解鉴权模型、限流阈值、状态机流转、回调机制与异常处理约定。
- 测试与验收人员:需要依据状态码、错误码与幂等语义设计用例并核对结果。
本页不覆盖产品功能说明与部署拓扑,相关内容见 产品能力、技术规格 与 内容保护。
1.2版本与状态标识
文档版本采用三段式编号,独立于产品版本演进:
| 字段 | 含义 | 变更触发 |
|---|---|---|
| MAJOR | 结构性调整:分组重组、错误码体系变更、鉴权模型变化 | 需重新评估既有集成 |
| MINOR | 新增接口、新增字段、新增事件类型 | 向后兼容,可增量接入 |
| PATCH | 勘误、表述修正、补充示例 | 不影响调用行为 |
本页当前为 v0.3.2。文档状态取值:
- 源码核对版(当前):路径、字段与状态码已写明;接口未规定的组织时效与合规策略也已直接标明,不再占位。
- 正式版:在核对版之上补齐每个端点的完整调用示例。
- 历史版:仅供回溯,不作为对接依据。
02通用约定#
2.1服务地址与通信协议
| 项目 | 取值 | 说明 |
|---|---|---|
| 默认监听 | 0.0.0.0:8200 | 服务端默认绑定地址与端口,可由部署配置调整 |
| API 前缀 | /api/v1 | 除健康检查与静态资源外,业务接口统一挂载于此前缀 |
| 传输协议 | HTTP(明文监听) | 服务本身以 HTTP 提供;生产环境建议由反向代理终止 TLS 后对外暴露 HTTPS |
| 报文编码 | UTF-8 | 请求与响应均按 UTF-8 编码 |
| 结构化请求体 | Content-Type: application/json | 文件上传除外,见 4.1 |
| 文件上传 | Content-Type: multipart/form-data | 走独立处理器,不受 JSON 体积上限约束 |
| 健康检查 | GET /health | 公开、无鉴权,用于存活探测 |
| 持久化 | SQLite 单文件库 | 默认位于数据目录下的媒体库文件,随部署配置变更 |
公开静态挂载(鉴权分组之外,知道路径即可访问)
| URL 前缀 | 默认目录 | 说明 |
|---|---|---|
| /uploads | {data.dir}/upload | 图片上传接口返回的 /uploads/<文件名> 落在此目录。媒体正片播放不走该前缀,走 /api/v1/media/:id/play |
| /atracks | {data.dir}/atracks | 预提取音轨 |
| /static/* | {data.dir}/static | 内置 /static/powerplayer6 优先于数据目录中的同名文件 |
| /metadata/library | {data.dir}/metadata/library | 刮削得到的海报、背景与标识 |
分片暂存目录默认 {data.dir}/upload/chunks,不对外挂载。HLS / DASH 清单与分片走 /api/v1 播放通道,不走上述静态前缀。
2.2身份鉴权与权限模型
PowerMedia 采用 JWT 令牌作为统一身份凭证,按访问面划分为四类鉴权通道。接入方必须明确自身调用落在哪一通道,因为令牌传递方式与可用端点不同。
| 通道 | 令牌传递 | 适用端点 | 约束 |
|---|---|---|---|
| 标准用户 / 机器令牌 | Authorization: Bearer <JWT> | 媒体库、上传、分享管理、任务管理等 | 仅接受请求头传令牌 |
| 播放通道 | Authorization: Bearer <JWT> 或 ?access_token=<JWT> | HLS / DASH / 预览 / 取图等 GET 类播放资源 | 额外允许查询参数传令牌,便于播放器直接拉流 |
| 分享匿名通道 | /api/v1/share/:token/… | 分享查看、校验、播放、下载与分享面 DRM 许可 | 凭分享令牌鉴权,无需用户 JWT;见 4.4 |
| JIT 会话通道 | 会话作用域令牌 | /api/v1/jit/session/:sessionID/… | 会话级授权,配合幂等键使用 |
| 项目 | 取值 / 说明 |
|---|---|
| 令牌算法 | HS256 签名 JWT,密钥由部署配置提供(security.jwt_secret) |
| 令牌有效期 | 默认 168 小时(7 天),由 security.token_hours 配置 |
| 身份字段 | user_id / username / role;机器令牌另带 app_id |
| 角色 | admin 为管理员;管理端点在标准鉴权之上再校验该角色 |
| 机器令牌 | 由 OAuth2 client_credentials 签发,app_id > 0 即判定为 API 客户端;不允许创建分享 |
| 登录获取令牌 | POST/api/v1/user/login、POST/api/v1/oauth/token(公开,无需令牌) |
| 端点 | 请求 | 成功响应 | 失败 |
|---|---|---|---|
| POST /api/v1/user/login | JSON:username、password,均为必填 | 200:token(JWT)、expires_in_hours(默认 168) | 缺字段 400;账号或密码错误 401 {"error":"invalid credentials"} |
| POST /api/v1/oauth/token | JSON 或表单:grant_type=client_credentials、client_id、client_secret | 200:access_token、token_type=Bearer、expires_in(秒,默认 168×3600) | 授权类型不符 400 unsupported_grant_type;缺凭据 400 invalid_request;凭据错误或已吊销 401 invalid_client |
用户登录在 can_manage=1 时把令牌角色写成 admin。机器令牌若绑定了用户,则继承该用户的用户名与角色;绑定用户不存在时退回通用机器身份。
2.3请求与响应通用结构
请求头通用项
| 请求头 | 类型 | 必填 | 说明 |
|---|---|---|---|
| Authorization | string | 条件必填 | Bearer <JWT>;公开端点与分享匿名面除外 |
| Content-Type | string | 条件必填 | 有请求体时必填;上传用 multipart/form-data |
| Idempotency-Key | string | 可选 | 写操作幂等键,见 2.5;格式 [A-Za-z0-9._:-]{8,128} |
| X-Request-Id | string | 可选 | 调用方侧追踪标识;服务端会在响应中回填自身 request_id,用于对齐访问日志 |
错误响应信封 服务端存在两套并行的错误响应形态,接入方必须同时处理,不可只解析其一。
{
"code": "session_expired",
"message": "session expired",
"request_id": "…",
"retryable": false,
"details": null
}
{
"error": "share quota exceeded for this media (max 20 active shares)",
"reason": "share_quota_exceeded"
}
- 形态 A 用于播放协议相关端点,字段固定五项,details 无内容时为 null 而非缺省;响应强制携带 Cache-Control: private, no-store。
- 形态 B 用于媒体库、上传、分享管理、管理端等业务路由,reason 为稳定的机器可读短码,error 为人读信息,两者均可能随版本演进。
- 建议接入方按「先取 code,再取 reason,最后取 error/message」的顺序解析,避免形态差异导致漏判。
成功响应 不存在统一成功包装;响应体直接返回资源对象或结果对象。
- 媒体列表 GET /api/v1/media 返回 {"items":[…]}。查询参数:library_id、file_type、q、sort(id_desc / created_desc / taken_desc,默认 id_desc)、limit(默认并上限 500;file_type=image 时上限 5000)、cursor(仅 sort=id_desc 时为上一条 id)。管理端未发布列表额外返回 has_more 与 next_cursor。
- 统一任务列表使用不透明游标(Base64 的版本、排序、过滤摘要与快照),limit 默认 50、上限 200,并带回同一快照下的总数。
- 分享列表使用 page 与 page_size,响应含 items、total、page、page_size。
- 没有全站统一的 offset 参数,也没有 {"data":…,"success":true} 这类外壳。
2.4参数类型、必填与限流
参数类型约定(全页统一使用):
| 类型 | 含义 | 取值约束 |
|---|---|---|
| string | 字符串 | 长度上限以字段说明为准 |
| int | 整数 | 按字段说明取值域 |
| bool | 布尔 | true / false |
| float | 浮点数 | 按字段说明取值域 |
| enum | 枚举 | 取值集合以字段说明为准,未知取值一律拒绝 |
| timestamp | 时间 | RFC 3339 / ISO 8601 |
| object | 嵌套对象 | 结构以字段说明为准 |
| array | 数组 | 元素类型以字段说明为准 |
必填标记:必填 = 缺失即拒绝;条件必填 = 视其他字段取值而定,条件写在说明列;可选 = 可缺省,缺省时取服务端默认值。
请求级限额
| 限制项 | 默认阈值 | 超限行为 |
|---|---|---|
| 请求 URL 长度 | 8 KiB | 鉴权前直接拒绝,不进入路由与请求体解析 |
| JSON 请求体 | 1 MiB | 拒绝;文件上传走 multipart,不受此项约束 |
| 每 IP 请求数 | 1200 次 / 分钟 | 拒绝,用于抑制单一来源请求洪泛 |
| 每 IP 并发 | 256 | 拒绝,避免突发请求占满处理槽 |
端点级限额(独立于上表)
- 外部播放计划:每 IP 默认 30 次/分钟,超限 429、code=rate_limited、retryable=true,并带 Retry-After。并发会话默认 4/IP。密钥拉取失败默认 30 次/分钟后封锁 120 秒。详见 4.2。
- 分享口令校验 POST /share/:token/verify:每 IP 默认 20 次/分钟(系统选项可调,钳制在 5–120),超限 429、reason=rate_limited、Retry-After: 60。
- 其余业务端点没有另一套独立配额;它们只受本节请求护栏约束。
2.5幂等、重试与回调约定
幂等
| 项目 | 约定 |
|---|---|
| 请求头 | Idempotency-Key |
| 取值格式 | [A-Za-z0-9._:-]{8,128},8–128 位 |
| 生效方法 | POST / PUT / PATCH / DELETE;GET 不参与 |
| 判定指纹 | SHA-256(方法 + "\n" + 路径 + "\n" + 请求体) |
| 作用域 | 「方法 + 路径 + 幂等键」三元组,同键不同路径互不影响 |
| 有效期 | 默认 10 分钟,超时后自动遗忘 |
| 请求体上限 | 1 MiB,超出直接拒绝 |
| 同键同体重放 | 放行至业务处理,用于安全重试 |
| 同键异体 | 409 idempotency_key_conflict,拒绝以防止重试时误用不同意图 |
| 键格式非法 | 400 invalid_idempotency_key |
| 请求体超限 | 413 request_body_too_large |
| 请求体不可读 | 400 invalid_request_body |
作用范围:幂等中间件挂载于 JIT 会话写操作与管理端生命周期触发接口(/admin/jit/lifecycle/run、/admin/jit/keys/lifecycle/run)。未挂载幂等中间件的写接口不保证重试安全,接入方须自行做前置查询或业务侧去重。各端点是否启用幂等,以 4.x 各节标注为准。
重试约定 客户端重试建议:仅对 retryable = true 或 5xx / 429 重试,采用指数退避并带上同一 Idempotency-Key。4xx(除 429)视为调用方错误,不应重试。服务端侧的重试策略见 6.x 各场景。
回调约定 服务端提供 Webhook 主动推送能力用于状态回传(事件清单、签名与重试见 6.5);同时提供任务状态查询接口作为兜底(见 4.3)。二者可并用,建议以 Webhook 为主、查询为辅。
03术语说明#
3.1产品术语
| 术语 | 说明 |
|---|---|
| 媒体库(Library) | 媒体资产的归集单元,拥有独立的目录、扫描任务与分类维度 |
| 媒体(Media) | 单个可播放/可查看的资产记录,含文件路径、类型、时长、尺寸、码率与元数据 |
| 入库(Ingest) | 文件落盘后登记为媒体记录并触发后续处理的阶段 |
| 后处理(Post-Ingest) | 入库完成后自动触发的处理链,如打包、预处理、元数据提取 |
| 预转码 / 预处理(Pretranscode) | 提前生成多码率播放产物的能力,属授权门槛功能 |
| 转码产物(Rendition) | 一个码率/分辨率档位的输出,多档构成阶梯(ladder) |
| 即时转码(JIT) | 按播放请求即时产出播放产物并建立会话的机制,含会话生命周期控制 |
| 播放计划(Playback Plan) | 播放前获取播放地址、能力协商与降级状态的接口返回 |
| 降级(Degradation) | 产能/容量受限时阶梯档位受限的状态,会随播放计划一并返回 |
| 分享(Share) | 为媒体生成的对外访问凭证,含有效期、口令、下载开关与访问日志 |
| 内容保护 / DRM | 播放链路的加密与许可控制,含 AES-128、Widevine、FairPlay 与私有方案 |
| 取证水印(Forensic Watermark) | 面向溯源的水印嵌入与提取、匹配能力 |
3.2接口与对接术语
| 术语 | 说明 |
|---|---|
| 端点(Endpoint) | 一个「HTTP 方法 + 路径」的组合,对应一个接口 |
| 请求体(Body) | 随请求提交的结构化数据,字段与类型见各接口字段表 |
| 错误信封(Error Envelope) | 错误响应的固定结构,见 2.3;本服务存在 A / B 两套形态 |
| 幂等键(Idempotency-Key) | 调用方生成的重试标识,见 2.5 |
| 机器令牌(Machine Token) | 由 OAuth2 客户端凭证签发的 JWT,app_id > 0 |
| Webhook | 服务端向调用方登记的回调地址主动推送事件的机制,见 6.5 |
| 事件(Event) | Webhook 推送的最小单元,带类型名、事件标识与时间戳 |
| 状态机(State Machine) | 任务在各状态间的合法流转规则,非法流转被拒绝 |
| 授权门槛功能(License-Gated) | 需有效授权方可使用的能力;未授权时接口返回拒绝 |
04API 参考#
4.0分组索引与条目规范
全部业务接口挂载于 /api/v1 之下,按鉴权通道先分组、再按功能域归类。下表为通道索引,各域端点见 4.1–4.6。
| 通道 / 分组 | 鉴权要求 | 覆盖范围 |
|---|---|---|
| 公开面 | 无鉴权 | 健康检查、品牌信息、登录、令牌签发、播放密钥、静态资源、外部播放计划 |
| 分享匿名组 /share/:token | 分享令牌 | 分享查看 / 校验 / 播放 / 预览 / 下载 / 分享面 DRM 许可 |
| 标准用户组 | JWT(仅请求头) | 用户资料、媒体库与目录、媒体查询、收藏、播放列表、分享管理、阅读进度 |
| 播放组 | JWT(请求头或 ?access_token=) | 播放入口、HLS / DASH / 取证清单、预览与封面、字幕、音轨、任务状态查询 |
| JIT 会话组 /jit/session/:sessionID | 会话令牌 + 幂等键 | 会话内资源拉取与会话控制(暂停 / 恢复 / 跳转 / 结束) |
| 文档解析组 /docreader | JWT | 解析引擎、解析任务提交与结果获取 |
| 管理组 /admin/… | JWT + 管理员角色 | 媒体库管理、入库重试、上传、任务编排、刮削与 AI 提供方、系统选项、水印、监控、用户与客户端、调度策略 |
| 预转码组 | JWT + 管理员 + 授权门槛 | 预设与档位、统一转码任务、产物清理、优化媒体、Webhook 配置、转码集群 |
接口条目规范 每个接口按下列结构描述,字段缺失即表示该维度尚未核实:
| 维度 | 内容 |
|---|---|
| 用途 | 接口解决什么问题、在流程中的位置 |
| 方法与路径 | HTTP 方法 + 完整路径 |
| 权限要求 | 所属鉴权通道 + 角色 / 授权门槛约束 |
| 请求字段 | 字段名、类型、必填性、取值约束、默认值 |
| 响应字段 | 字段名、类型、含义 |
| 响应状态 | 成功状态码与关键失败状态码 |
| 错误码 | 触发的 code / reason 及处置建议 |
4.1媒体与入库#
本域覆盖文件上传、入库登记、媒体查询与目录浏览。上传成功后服务端自动触发打包、(视频)即时转码预处理与入库后处理,接入方无需另行调起。
| 方法 | 路径 | 用途 | 权限 |
|---|---|---|---|
| POST | /api/v1/upload | 单文件上传入库 | 管理 |
| POST | /api/v1/upload/dedupe-check | 上传前查重 | 管理 |
| POST | /api/v1/upload/reuse | 复用既有文件登记新媒体 | 管理 |
| POST | /api/v1/upload/mkdir | 创建上传目标目录 | 管理 |
| POST | /api/v1/upload/image | 图片上传 | 管理 |
| POST | /api/v1/upload/chunk | 分片上传 | 管理 |
| POST | /api/v1/upload/merge | 分片合并 | 管理 |
| GET | /api/v1/media | 媒体列表 | 标准用户 |
| GET | /api/v1/media/:id | 媒体详情 | 标准用户 |
| GET | /api/v1/media/:id/meta | 媒体元数据 | 标准用户 |
| GET | /api/v1/media/:id/stats | 媒体统计 | 标准用户 |
| GET | /api/v1/library | 媒体库列表 | 标准用户 |
| GET | /api/v1/library/:id/… | 库内系列 / 专辑 / 艺人 / 流派 / 曲目 / 照片 / 文档等分面查询 | 标准用户 |
| POST | /api/v1/library | 创建媒体库 | 管理 |
| POST | /api/v1/library/:id/scan | 发起目录扫描 | 管理 |
| GET | /api/v1/scan/task | 扫描任务列表 | 管理 |
| GET | /api/v1/admin/media | 管理端媒体列表 | 管理 |
| GET | /api/v1/admin/media/:id/ingest | 入库状态查询 | 管理 |
| POST | /api/v1/admin/media/:id/ingest/retry | 入库重试 | 管理 |
单文件上传 POST/api/v1/upload
用途:上传单个文件并登记为媒体记录;服务端自动计算 MD5 与感知哈希、探测媒体参数,并触发后续处理链。
权限要求:管理通道(JWT + 管理员)。请求体类型:multipart/form-data。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| file | file | 必填 | 上传文件本体;缺失时返回 400 {"error":"file required"} |
| library_id | int | 可选 | 目标媒体库标识;缺省时按上传目标目录解析 |
| target_dir | string | 可选 | 目标目录;与 library_id 共同决定落盘位置 |
| title | string | 可选 | 媒体标题;缺省时取上传文件名 |
| 字段 | 类型 | 含义 |
|---|---|---|
| id | int | 新媒体记录标识 |
| file_id | string | 文件标识 |
| path | string | 文件落盘路径;命中去重时指向既有物理文件 |
| md5 | string | 文件 MD5 |
| deduped | bool | 可选。命中感知哈希去重时返回 true |
- 去重语义:相同字节内容只保留一份物理文件,但每次上传仍新建一条媒体记录,各自独立维护元数据。
- 自动触发:上传成功后自动入队打包任务;视频类型额外触发即时转码预处理;并提交入库后处理任务。
- 服务端探测:自动计算 MD5、感知哈希,并探测时长、宽、高、码率与容器格式。
- 响应状态:成功 200;缺文件 400;存储失败 500。
- 大小与类型:单文件与分片上传都没有应用层字节上限;1 MiB 上限只约束 JSON 请求体。扩展名不作为拒绝条件,只用于分类:视频、音频、图片、文档,其余为 other。分类表可由 scan.file_extensions 整类替换,省略则用内置表。扫描入库才按扩展名过滤;上传接口本身不拒收未知扩展名。
- 临时文件:命中感知哈希去重时删除刚写入的副本。分片在合并成功后删除该 upload_id 目录。没有分片目录的定时清扫,未合并的分片会留在 {data.dir}/upload/chunks。
分片上传(/upload/chunk · /upload/merge)字段定义
POST /upload/chunk 为 multipart/form-data:upload_id(可选,缺省由服务端生成 UUID)、index(必填整数)、file(必填分片)。成功 200 返回 upload_id 与 index。分片落盘为 {chunks}/{upload_id}/{index:08d}.part,同一序号再次上传会覆盖该分片。没有单分片字节上限。
POST /upload/merge 为 JSON:upload_id、filename、total_parts 必填;library_id、target_dir、title 可选。服务端按 0 … total_parts-1 顺序拼接,缺任一分片返回 400。成功响应在单文件字段之外多一个整文件 sha256。合并成功后删除该分片目录。
- 没有「查询已收分片」接口。客户端保存每次 200 回执中的 upload_id 与 index,缺片时用同一 upload_id 重传对应序号,即可续传。
- 没有独立秒传协议。合并或单文件上传在写入后按感知哈希查找已有文件,命中则删掉新副本并新建一条媒体记录,响应 deduped=true。
入库与后处理状态机(Ingest / Post-Ingest)
GET /admin/media/:id/ingest 返回当前代际的入库运行。媒体不存在 404 media not found;没有当前运行 404 current ingest run not found。重试 POST …/ingest/retry:无可重试工作 409 no retryable work,成功后再返回同一份入库视图。
- 媒体发布状态:processing、published、degraded、failed、cancelled。扫描或上传创建运行后为 processing;发布策略在必选步骤完成后写成 published,部分失败为 degraded,无法完成为 failed,被新代际取代为 cancelled。查询接口拒绝这五个之外的过滤值。
- 运行 run.status:与发布状态同一组取值,进行中为 processing。Webhook 在 published 或 degraded 时发 run.completed,在 failed 时发 run.failed;processing 与 cancelled 不发运行级事件。
- 步骤 steps[].status:waiting → running → done / failed / skipped / cancelled。工作者认领后进入 running;成功为 done,耗尽尝试为 failed,可选步骤跳过为 skipped,代际被取代为 cancelled。步骤类型顺序:poster、thumbnail、scrape、preview、keyframe、subtitle、atrack、encrypt、prepare。
- 响应:media(id、publication_state、publication_error、published_at、ingest_generation)、run(id、generation、status、reason、preserve_visibility、error、时间戳、policy_version、terminal_reason)、steps[](id、type、required、status、attempts、max_attempts、租约与错误)、以及 dependencies、evidence、metadata_diagnostics、adapter_unavailable、unresolved_recovery_errors。
4.2播放与授权#
本域覆盖播放计划获取、播放入口、HLS / DASH 资源拉取、预览与封面、字幕与音轨。播放类 GET 资源允许通过 ?access_token= 传递令牌,便于播放器直接拉流。
| 方法 | 路径 | 用途 | 权限 |
|---|---|---|---|
| POST | /api/v1/public/playback/plan | 外部播放计划(第三方源即时播放) | 公开 / 可配置关闭 |
| GET | /api/v1/play/keys/:keyID | HLS AES-128 密钥下发 | 公开(按密钥作用域校验) |
| GET | /api/v1/media/:id/play | 播放入口 | 播放 |
| POST | /api/v1/media/:id/playback/start | 上报播放开始 | 播放 |
| POST | /api/v1/media/:id/playback/end | 上报播放结束 | 播放 |
| GET | /api/v1/media/:id/hls | HLS 信息 | 播放 |
| GET | /api/v1/media/:id/hls/*asset | HLS 清单与分片 | 播放 |
| GET | /api/v1/media/:id/dash/*asset | DASH 清单与分片 | 播放 |
| GET | /api/v1/media/:id/pretranscode/info | 预转码产物信息 | 播放 |
| GET | /api/v1/media/:id/forensic/… | 取证播放清单 / 初始化 / 分片 | 播放 |
| GET | /api/v1/media/:id/preview | 预览信息 | 播放 |
| GET | /api/v1/media/:id/preview/sprite.jpg | 预览雪碧图 | 播放 |
| GET | /api/v1/media/:id/preview/thumbs.vtt | 预览缩略图索引 | 播放 |
| GET | /api/v1/media/:id/poster.jpg | 封面图 | 播放 |
| GET | /api/v1/media/:id/photo/… | 照片预览 / 缩略 / 中图 | 播放 |
| GET | /api/v1/media/:id/document/… | 文档封面 / 预览 PDF / 分页图 | 播放 |
| GET | /api/v1/media/:id/subtitles/:sid/vtt | 字幕 VTT | 播放 |
| POST | /api/v1/subtitles/translate | 字幕翻译 | 播放 |
| GET | /api/v1/media/:id/atrack/:stream/… | 独立音轨清单与分片 | 播放 |
| GET | /api/v1/transcode/task/:id/status | 转码任务状态查询 | 播放 |
外部播放计划 POST/api/v1/public/playback/plan
用途:对第三方 URL 源发起即时播放,由服务端探测源、建立会话并返回播放地址与能力协商结果。该接口不在标准 JWT 通道内,可由部署配置整体关闭或要求匿名访问开关。GET 调用返回 405。
| 字段 | 类型 | 含义 |
|---|---|---|
| mode | string | 播放模式,固定为 jit_hls |
| play_url | string | 可直接播放的地址 |
| hls_master | string | HLS 主清单地址(与 play_url 同值) |
| session_id | string | 播放会话标识 |
| expires_in | int | 剩余有效秒数 |
| expires_at | timestamp | 会话到期时刻,RFC 3339 |
| profile_version | string | 输出配置版本 |
| rendition | string | 本次选定的档位名 |
| degradation | object | 降级状态,含 level 等;随响应头 X-Degradation-Level 同步下发 |
| capabilities | object | adaptive / seek / resume / drm |
| p2p | object | P2P 能力,当前恒为 {"enabled": false} |
| source | object | 源信息:duration_ms / width / height |
| cache | object | 缓存命中信息(含 hit / served_from_cache) |
| compatibility | object | direct_play(恒为 false)、source_video、output_profile、profile_reused;被拒绝复用时另含 profile_invalidated |
| encryption | object | 可选。仅受保护内容返回,否则不出现 |
| 限制项 | 默认值 | 说明 |
|---|---|---|
| 计划请求频率 | 30 次 / 分钟 / IP | 独立于全局限流 |
| 并发会话 | 4 / IP 200 / 节点 | 租户级上限可配 |
| 源文件大小 | ≤ 50 GiB | 超出拒绝 |
| 源时长 | ≤ 24 小时 | 超出拒绝 |
| 源端口 | 仅 80 / 443 | 其余端口拒绝 |
| 重定向次数 | ≤ 3 | 超出拒绝 |
| 内网源 | 默认禁止 | 防 SSRF |
| 会话令牌有效期 | 900 秒 | 会话空闲超时同为 900 秒 |
| 源探测缓存 | 600 秒 | 探测结果复用时长 |
响应状态:成功 200;方法不符 405;触发独立限额时按限流处理;源不可达 / 探测失败 / 产能不足按 5.2 错误码返回。
播放入口与 HLS / DASH 资源字段定义
GET /media/:id/play 成功一律 200 JSON,没有单独的档位协商请求。下表是各分支都会出现或按模式出现的键。
- mode:native、hls、hls_aes_128、hls_powerdrm、hls_drm、dash、jit_hls。进程内会话选择 DASH 时为 jit_dash,此时用 dash_mpd 替换 hls_master(把 master.m3u8 换成 manifest.mpd)。
- 直链:playUrl、mime_type、media_profile、client_caps、message。
- HLS:hls_master(绝对 URL,指向 /api/v1/media/:id/hls/master.m3u8)、status(已完成产物为 done,即时转码为 processing)、fallback(再次请求本播放入口)、可选 task_id。
- DASH:mode=dash 时另给清单 URL /api/v1/media/:id/dash/manifest.mpd。
- 即时转码:session_id,hls_master 指向 /api/v1/jit/session/:sessionID/master.m3u8。只有 jit.legacy_fallback_enabled 为 true、且进程内会话创建失败时,才回退到 Redis 旧链路:mode 仍是 jit_hls,hls_master 指向 /api/v1/jit/master/:fileId,并另给 jit_session_pause_url、jit_session_resume_url、jit_session_end_url、jit_session_seek_url。该开关默认关闭。
- 加密:drm 对象可含 widevine_license_url、widevine_transport(json_local 或 raw)、powerdrm_key_url、fairplay_cert_url、fairplay_license_url,配置开启时还有 widevine_service_cert_url。请求若带了 access_token,这些 URL 会原样附上同一查询参数。
- 清单与分片本身是 HLS / DASH 字节,不是 JSON。分片未就绪见 5.2 segment_not_ready。
- 播放协议面错误走 2.3 形态 A 信封,码表见 5.2。
- 查询参数令牌:播放通道接受的 access_token 就是登录或 OAuth 签发的同一枚 JWT,声明仍是 user_id / username / role / 可选 app_id,有效期仍是 security.token_hours(默认 168 小时)。它不绑定到单个媒体。标准用户组与管理组不接受查询参数,只认 Authorization。查询参数会出现在访问日志与播放器引用中,只应放在播放 GET 上。
- 外部播放的 play_token 是另一枚会话令牌,寿命默认等于会话空闲时间加 60 秒,并且不超过 900 秒、不低于 60 秒。它只用于外部播放计划建立的会话,不能当作用户 JWT。
4.3转码与任务#
本域覆盖转码任务提交与编排、各类处理任务队列(预览 / 字幕 / 歌词 / 音轨 / 关键帧 / 加密)以及统一任务控制。任务控制面提供注册表、总览、列表、详情与动作执行。
| 方法 | 路径 | 用途 | 权限 |
|---|---|---|---|
| GET | /api/v1/transcode/task/:id/status | 转码任务状态 | 播放 |
| POST | /api/v1/transcode/async | 提交异步转码 | 管理 |
| GET | /api/v1/transcode/task | 转码任务列表 | 管理 |
| POST | /api/v1/transcode/task/:id/cancel|retry | 取消 / 重试 | 管理 |
| POST | /api/v1/transcode/task/batch | 批量转码 | 管理 |
| GET | /api/v1/preview/task | 预览任务列表 | 管理 |
| GET | /api/v1/subtitle/task | 字幕任务列表 | 管理 |
| GET | /api/v1/lyric/task | 歌词任务列表 | 管理 |
| GET | /api/v1/atrack/task | 音轨提取任务列表 | 管理 |
| GET | /api/v1/keyframe/task | 关键帧任务列表 | 管理 |
| GET | /api/v1/encrypt/task | 加密任务列表 | 管理 |
| POST | /api/v1/media/:id/encrypt-assets | 触发媒体资源加密 | 管理 |
| POST | /api/v1/media/:id/atrack | 触发音轨提取 | 管理 |
| POST | /api/v1/media/:id/keyframe | 触发关键帧提取 | 管理 |
| GET | /api/v1/admin/tasks/registry | 任务注册表 | 管理 |
| GET | /api/v1/admin/tasks/overview | 任务总览 | 管理 |
| GET | /api/v1/admin/tasks | 任务列表 | 管理 |
| GET | /api/v1/admin/tasks/:task_id | 任务详情 | 管理 |
| POST | /api/v1/admin/tasks/:task_id/actions | 任务动作执行 | 管理 |
| POST | /api/v1/admin/tasks/batch | 批量任务动作 | 管理 |
| GET | /api/v1/admin/tasks/stream | 任务流式推送 | 播放通道 |
| GET | /api/v1/schedule/task | 定时任务列表 | 管理 |
| POST | /api/v1/schedule/task | 创建定时任务 | 管理 |
统一任务控制 GET/api/v1/admin/tasks/:task_id
用途:按任务标识查询任意类型处理任务的详情,是状态回传的兜底通道(Webhook 见 6.5)。权限:管理通道。
请求字段:task_id(路径参数,string,必填)。控制面不可用 500 task_control_unavailable;不存在 404 task_not_found。
- 详情:row 为投影行,含 task_id、source_kind、source_id、task_type、family、normalized_status、raw_status、revision、generation、retry_round、attempt、max_attempts、优先级、时间、media_id、library_id、admission、owner_lease、terminal_reason、allowed_actions(abort / remove / reset / run_now / skip / reopen 布尔值)。同级还有 attempts、dependencies、evidence、audit_events。
- 规范化状态:waiting、running、done、failed、cancelled、skipped。原始值 pending/queued/ready 归入 waiting,processing/active/in_progress 归入 running,completed/success/finished 归入 done,error/abandoned 归入 failed。终态是后四者。各队列表的原始状态经这一映射对外展示,不另维护第二套状态机。
- 动作 POST …/actions,JSON:action 取 abort、cancel、remove、reset、run_now、skip、reopen;reason 必填。可选期望值 expected_revision、expected_generation、expected_retry_round。未知动作 400 unknown_action;缺原因 400 missing_reason;版本冲突 409 stale_revision 或 conflict;当前状态不允许 400 invalid_operation。成功 200,含 status=ok、action、task_id 与更新后的 row。
- 重试:入库步骤的 max_attempts 在入队时写入。刮削(网络步骤)默认 3 次,海报、预览、字幕、音轨、关键帧、加密等本地步骤默认 1 次。这是行为默认值;旧库列表的列默认值仍可能是 3,以行上的 max_attempts 为准。失败后由调度器按 available_at 再次认领,接口不承诺固定的秒级退避公式。客户端不要对 failed 自行空转重试,应调用 reset 或对应队列的 retry 端点。播放侧 capacity_exceeded 与 segment_not_ready 才按 retryable=true 退避。
- SSE GET /admin/tasks/stream:text/event-stream。查询参数 since_revision 用于断线续传。帧类型为 snapshot、delta、heartbeat、resync,JSON 含 id、revision、type、payload。有 id 时写成 SSE id: 行。心跳默认 30 秒;无负载的心跳是注释行 : heartbeat。订阅开始时先推当前快照。
4.4内容保护与分享#
本域覆盖分享的创建与管理、分享匿名访问面,以及播放链路的内容保护(密钥与许可下发)。分享功能属授权门槛能力:未授权或被管理员关闭时,相关接口直接拒绝。机器令牌不得创建分享。
| 方法 | 路径 | 用途 |
|---|---|---|
| POST | /api/v1/shares 或 /api/v1/media/:id/shares | 创建分享 |
| GET | /api/v1/shares 或 /api/v1/media/:id/shares | 分享列表 |
| GET | /api/v1/shares/:id | 分享详情 |
| PUT | /api/v1/shares/:id | 更新分享 |
| DELETE | /api/v1/shares/:id | 删除分享 |
| POST | /api/v1/shares/:id/revoke | 撤销分享 |
| POST | /api/v1/shares/:id/rotate | 轮换分享令牌 |
| POST | /api/v1/shares/:id/regenerate-code | 重置访问口令 |
| POST | /api/v1/shares/:id/unlock | 解锁访问口令 |
| GET | /api/v1/shares/:id/access-log | 分享访问日志 |
| POST | /api/v1/shares/batch-revoke | 批量撤销 |
| GET | /api/v1/shares/audit.csv | 导出分享审计 |
创建分享 POST/api/v1/shares
用途:为指定媒体生成对外分享凭证。媒体标识既可放在请求体,也可放在路径(/api/v1/media/:id/shares),二者取其一。
权限要求:标准用户组(JWT);机器令牌(app_id > 0)调用返回 403,reason = share_not_allowed_for_api_client。请求体类型:application/json。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| media_id | int | 条件必填 | 媒体标识;可由路径参数 :id 提供。两者皆缺时返回 400 |
| expire_hours | int | 可选 | 有效期小时数;缺省取默认值,-1 表示永不过期 |
| expires_in | string | 可选 | 有效期别名:60m / 24h / 7d / never / first_view_24h。与 expire_hours 二选一,非法取值返回 reason=invalid_expires_in |
| expire_after_first_view_minutes | int | 可选 | 首次访问后多少分钟过期;expires_in 使用 first_view_24h 时由服务端换算写入 |
| use_access_code | bool | 可选 | 是否启用访问口令 |
| enable_code | bool | 可选 | 别名,等价于 use_access_code,同时提供时以后者为准 |
| access_code | string | 条件必填 | 访问口令;启用口令时提供 |
| allow_download | bool | 可选 | 是否允许下载 |
| autoplay | bool | 可选 | 是否自动播放,仅对音视频生效;缺省为 true |
| note | string | 可选 | 备注,去除首尾空白后不超过 50 个字符,超出返回 reason=note_too_long |
| 约束 | 行为 |
|---|---|
| 功能开关 | 分享功能被管理员关闭时返回 503,reason=share_disabled |
| 活跃分享配额 | 单个媒体的活跃分享数达到上限(默认 20)返回 409,reason=share_quota_exceeded |
| 不可分享类型 | 无可分享入口的媒体类型被拒绝,reason=nothing_shareable_for_type |
| 仅下载型媒体 | 无内联预览入口的类型必须允许下载,否则拒绝 |
| 有效期越界 | reason=expire_hours_out_of_range / expires_exceeds_max_days / allow_never_expiry_disabled |
| 首访有效期越界 | reason=first_view_out_of_range |
响应状态:成功 200(创建不返回 201);参数缺失或非法 400;机器令牌 403;配额超限 409;功能关闭 503。未授权分享能力时管理面返回 403。
- 创建成功在分享对象上额外给出明文 token(仅此一次;库中只存 SHA-256)、share_url 与同值的 url、embed_url(url + /embed)、允许下载时的 download_url,否则为 null、带口令时的 url_with_code,以及 server_now(RFC 3339 UTC)。
- 对象字段:id、media_id、media_title、media_type、created_by、created_by_name、scope(固定 play,preview,download)、has_access_code、access_code(创建或显式揭示时才有明文)、allow_download、autoplay、expires_at、expire_after_first_view_minutes、first_viewed_at、effective_expires_at、status、invalid_reason、access_count、last_access_at、locked、locked_until、note、created_at、updated_at。
- 令牌是 16 字节随机数的 Base64 URL 编码(128 位熵)。撤销或轮换后,下一次匿名请求按库中当前哈希校验,没有额外的失效延迟。
| 方法 | 路径(相对分享前缀) | 用途 |
|---|---|---|
| GET | /info | 分享基本信息 |
| POST | /verify | 口令校验(GET 返回 405) |
| GET | /play | 播放 |
| GET | /play/*asset | 播放资源 |
| GET | /preview | 预览 |
| GET | /preview/sprite.jpg | 预览雪碧图 |
| GET | /preview/thumbs.vtt | 预览缩略索引 |
| GET | /poster | 封面 |
| GET | /lyrics | 歌词 |
| GET | /document/preview.pdf | 文档预览 |
| GET | /document/page/:page | 文档分页图 |
| GET | /document/cover | 文档封面 |
| GET | /download | 下载(受分享下载开关约束) |
| GET | /drm/key | HLS AES-128 密钥 |
| GET | /drm/widevine/service-cert | Widevine 服务证书 |
| POST | /drm/widevine/license | Widevine 许可 |
| GET | /drm/fairplay/cert | FairPlay 证书 |
| POST | /drm/fairplay/license | FairPlay 许可 |
| 方案 | 默认状态 | 说明 |
|---|---|---|
| HLS AES-128 | 启用 | 密钥经专用端点下发,按作用域校验 |
| Widevine | 默认关闭 | 需配置私有合规模块端点;可选下发服务证书 |
| FairPlay | 启用 | 证书与许可端点齐备 |
| 私有方案(PowerDRM) | 默认开启 | 与自有播放器配合 |
| 打包引擎 | Shaka 优先,ffmpeg 回退 | CENC fMP4 HLS,分片默认 4 秒 |
| 取证水印 | 独立能力 | 嵌入、提取、溯源匹配,见 4.6 |
匿名面字段匿名响应不返回内部媒体 id 或用户 id。
- GET /info:status、require_code、verified、allow_download、has_access_code、server_time,以及算出的 effective_expires_at。未校验口令时只加 media_type;管理员打开「校验前预览」后,音视频还可看到 title 与 poster_url。校验通过后增加 title、duration、width、height、created_at、access_count,音视频还有 autoplay、poster_url 与容器 mime_type。令牌无效 404 reason=invalid_token;媒体已不存在 410 reason=media_missing。
- POST /verify,JSON code。无口令或校验成功均为 200 {"ok":true,"verified":true},成功时写分享会话 Cookie。跨站 403 origin_mismatch;口令错 403 code_invalid;锁定 403 code_locked 并带 Retry-After。GET 该路径 405 method_not_allowed。
- GET /play 在已有 HLS 主清单时直接返回 application/vnd.apple.mpegurl,否则以内联方式输出媒体字节(加密源在内存中解密)。它不是 JSON 播放计划。/play/*asset 返回对应分片或初始化段。
- 播放令牌见 4.2。分享令牌为 16 字节随机数的 Base64 URL 编码,库中只存 SHA-256。撤销、轮换或过期在下一次请求生效,没有单独的失效延迟。
4.5AI 媒体处理#
本域覆盖 AI 任务的提交与查询、AI 服务提供方配置、刮削与元数据补全、字幕 / 歌词 / 文档解析、照片人脸与分类等智能处理。本机引擎可离线运行;只有打开的刮削站点或大模型提供方才会把文本发到服务之外。
| 方法 | 路径 | 用途 | 权限 |
|---|---|---|---|
| GET | /api/v1/ai-provider | AI 提供方列表 | 管理 |
| PUT | /api/v1/ai-provider/:id | 保存 AI 提供方 | 管理 |
| POST | /api/v1/ai-provider/:id/test | 连通性测试 | 管理 |
| POST | /api/v1/media/:id/scrape | 触发元数据刮削 | 管理 |
| GET | /api/v1/scrape/… | 刮削配置、任务、历史、检索 | 管理 |
| POST | /api/v1/media/:id/subtitle/process | 字幕处理 | 管理 |
| POST | /api/v1/media/:id/subtitles/import | 字幕导入 | 管理 |
| GET | /api/v1/media/:id/subtitles/:sid/cues | 字幕字幕条查询 | 管理 |
| PUT | /api/v1/media/:id/subtitles/:sid/cues | 字幕条保存 | 管理 |
| POST | /api/v1/media/:id/lyrics/recognize | 歌词识别 | 管理 |
| POST | /api/v1/subtitles/translate | 字幕翻译 | 播放 |
| GET | /api/v1/docreader/engines | 文档解析引擎 | 标准用户 |
| POST | /api/v1/docreader/parse | 提交文档解析 | 标准用户 |
| GET | /api/v1/docreader/task/:id | 解析任务查询 | 标准用户 |
| GET | /api/v1/docreader/task/:id/result | 解析结果 | 标准用户 |
| POST | /api/v1/docreader/task/:id/cancel | 取消解析 | 标准用户 |
| POST | /api/v1/library/:id/photo/classify | 触发照片分类 | 管理 |
| POST | /api/v1/library/:id/photo/faces/backfill | 人脸回填 | 标准用户 |
| GET | /api/v1/photo/face/:id/thumb.jpg | 人脸缩略图 | 播放 |
| 能力域 | 配置 / 测试端点 |
|---|---|
| 语音识别(ASR) | /admin/system-options/test|install/asr |
| 文字识别(OCR) | /admin/system-options/test|install/ocr |
| 照片分类 | /admin/system-options/test|install/photo-classify |
| 人脸识别 | /admin/system-options/test|install/photo-face |
| 文档转换 | /admin/system-options/test|install/doc-trans |
| 文档解析 | /admin/system-options/test|install/docreader |
- 数据出域:没有保留期限或合规策略字段。出域与否由启用的引擎决定。本机工具(FFmpeg、Whisper / Paraformer、字幕 OCR、照片分类、InsightFace、LibreOffice 文档转换)在进程所在机器上读写文件,不另建外发通道。刮削提供方(TMDB、TVDB、豆瓣、Bangumi、OMDb 等)与已配置的大模型(OpenAI、DeepSeek、通义、Ollama)只在对应提供方开启时,把检索词、字幕或校对文本发往该提供方;关闭提供方即不再调用。结果写回媒体元数据、字幕或任务行,不另设云端副本。
- AI 与后处理任务的状态与结果位置见 4.3 的规范化状态和 4.1 的入库步骤。字幕、歌词、预览等队列各自有 retry 端点;重试次数见 4.3 入库步骤的默认次数。
- 可离线运行的引擎:ASR、OCR、照片分类、人脸、文档转换、文档解析。系统选项里对应 /admin/system-options/test|install/…。未安装或检测失败时任务失败,不会自动改走公网。
4.6平台与系统#
本域覆盖账号与令牌、授权与授权门槛查询、系统选项、水印与取证、监控与日志、用户与 API 客户端管理、调度策略与转码集群。
| 方法 | 路径 | 用途 | 权限 |
|---|---|---|---|
| GET | /health | 存活探测 | 公开 |
| POST | /api/v1/user/login | 用户登录 | 公开 |
| POST | /api/v1/oauth/token | OAuth2 令牌签发 | 公开 |
| GET | /api/v1/branding | 品牌信息 | 公开 |
| GET | /api/v1/user/info | 当前用户信息 | 标准用户 |
| PUT | /api/v1/user/profile | 更新资料 | 标准用户 |
| PUT | /api/v1/user/password | 修改密码 | 标准用户 |
| POST | /api/v1/user/logout | 登出 | 标准用户 |
| GET | /api/v1/license/features | 授权功能清单 | 标准用户 |
| GET | /api/v1/client-guard | 客户端防护配置 | 标准用户 |
| GET | /api/v1/admin/system-options | 系统选项 | 管理 |
| PUT | /api/v1/admin/system-options | 更新系统选项 | 管理 |
| GET | /api/v1/admin/watermark/capabilities | 水印能力 | 管理 |
| POST | /api/v1/admin/watermark/extract | 水印提取 | 管理 |
| POST | /api/v1/admin/forensic/match | 取证匹配 | 管理 |
| GET | /api/v1/admin/overview | 管理总览 | 管理 |
| GET | /api/v1/admin/access-log | 访问日志 | 管理 |
| GET | /api/v1/admin/system-logs/… | 运行日志 / 访问日志查询与下载 | 管理 |
| GET | /api/v1/admin/monitoring/metrics | 监控指标 | 管理 |
| GET | /api/v1/admin/api-clients | API 客户端列表 | 管理 |
| POST | /api/v1/admin/api-clients | 创建 API 客户端 | 管理 |
| GET | /api/v1/admin/users | 用户管理 | 管理 |
| GET | /api/v1/admin/scheduler/policy | 调度策略 | 管理 |
| POST | /api/v1/admin/scheduler/control|explain | 调度控制 / 任务解释 | 管理 |
| GET | /api/v1/admin/security/key-material-scan | 密钥材料扫描 | 管理 |
| GET | /api/v1/admin/jit/overview|cost|budget|lifecycle|degradation | 即时转码治理 | 管理 |
| 能力 | 代表端点 |
|---|---|
| 预设与档位管理 | /admin/settings/pretranscode-presets… |
| 统一转码任务 | /admin/transcode/tasks… /admin/transcode/batch |
| 档位作业控制 | /admin/transcode/tasks/:id/renditions… |
| 产物与存储清理 | /admin/transcode/storage /admin/transcode/cleanup… |
| 优化媒体管理 | /admin/optimization/media… |
| Webhook 配置 | /admin/settings/pretranscode-webhooks… |
| 转码集群 | /admin/transcode/cluster/nodes|stats|baseline /admin/transcode/encoders |
- 未授权:预转码组一律 403。许可证模块未初始化:{"error":"license module not initialized"}。许可证过期:code=license_expired。功能未包含:code=feature_not_licensed,并带 feature 与 reason。试用额度用尽:code=trial_limit_reached。分享管理面在未授权时同样 403,code=feature_not_licensed、error=Share Not Licensed;已经发出的匿名链接不因授权降级而失效。播放并发或播放授权失败走 403,码为 license_expired、license_concurrency_exceeded 或 license_not_entitled。
- 系统选项:GET/PUT /admin/system-options 读写单行 JSON。顶层键为 general、playback、transcoder、recognition、photo_classify、photo_face、doc_trans、share、watermark、image_protect、doc_protect、client_harden。分享段默认:开启、默认有效期 24 小时、不允许永久、不强制口令、默认不允许下载、口令校验 20 次/分钟、5 次失败锁定 15 分钟、口令 4 位、最长 30 天、会话 2 小时、每媒体 20 条活跃分享、校验前不展示预览、访问日志保留 90 天。其余段以 GET 返回的当前值为准,本页不另抄一份会随版本变化的嵌套默认值。
- API 客户端:POST /admin/api-clients,JSON name(必填)、description、user_id(可选,须是已有用户)。成功 201,返回 app_id、client_id(knox_ 加 16 字节十六进制)、client_secret(32 字节十六进制,仅本次)。库中只存 bcrypt 哈希。没有轮换接口:吊销是 DELETE /api/v1/admin/api-clients/:id(成功 {"ok":true}),之后新建一条。吊销后换票返回 401 invalid_client。
4.7其他#
4.1–4.6 里用省略号带过的路径,以及只在商业模块注册的路径,在此按路径补全。除另行注明外,路径都在 /api/v1 下。同一行用 | 连接的是同一资源的不同方法或别名,行为相同。
| 方法 | 路径 | 说明 |
|---|---|---|
| POST / DELETE | /user/avatar | 上传或删除头像 |
| GET | /user/history | 当前用户播放记录 |
| GET | /playback-history | 播放历史列表 |
| POST | /user/parental/unlock | 家长控制解锁 |
| GET / POST / DELETE | /favorites /media/:id/favorite | 收藏列表、单条状态、加入与取消 |
| GET / POST / PUT / DELETE | /favorite-folders /favorite-folders/:id /favorite-folders/:id/items /favorite-folders/:id/items/:itemId | 收藏夹及其条目 |
| GET / POST / PUT / DELETE | /playlists /playlists/:id /playlists/:id/items /playlists/:id/items/:itemId /playlists/:id/reorder /playlists/:id/images/:field | 播放列表、条目排序与封面 |
| POST / DELETE | /media/:id/progress | 保存或清除播放进度 |
| PUT / DELETE | /media/:id/watched | 标记或取消已看,两个方法走同一处理 |
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /library/:id/series|albums|artists|genres|tracks | 剧集、专辑、艺人、流派、曲目 |
| GET | /library/:id/genre/albums | 某流派下的专辑 |
| PATCH | /library/:id/genre | 修改库内流派 |
| GET / PATCH | /album/:id /album/:id/play-target /album/:id/image-candidates /artist/:id /artist/:id/albums /artist/:id/image-candidates | 专辑与艺人详情、起播目标和候选图 |
| GET / PATCH | /series/:id /series/:id/play-target /series/:id/image-candidates /season/:id/episodes | 剧集系列、季内分集 |
| GET | /library/:id/photo/categories|places|persons | 照片分类、地点、人物 |
| POST / GET | /library/:id/photo/locations/backfill …/locations/progress …/faces/backfill …/faces/progress …/classify/progress | 地点回填、人脸回填与各自进度。分类入队仍是管理端 POST /library/:id/photo/classify |
| PATCH | /library/:id/photo/persons/:personId /media/:id/photo/tags | 改人物名称、改照片标签 |
| GET / PATCH / POST | /library/:id/documents|document/nodes|document/facets|documents/recent /media/:id/document /media/:id/document/preview/info /media/:id/read-progress /documents/download /documents/tags | 文档列表、目录、分面、详情、阅读进度、批量下载与批量改标签 |
| GET | /scan-logs | 扫描日志 |
| GET / POST / PATCH / DELETE | /persons /persons/search /person/:id /person/:id/works|collaborators | 演职人员检索与作品。创建、修改、删除和刮削入队在管理通道:POST /persons、PATCH|DELETE /person/:id、POST /person/:id/scrape、/person/scrape/tasks、GET /cast/stats |
| GET / POST / PATCH / DELETE | /media/:id/persons /media/:id/persons/:linkId /media/:id/import-credits /library/:id/import-credits | 媒体演职员关联与从 TMDB 导入。写操作在管理通道 |
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /media/:id/preview /preview/sprite.jpg /preview/thumbs.vtt /poster.jpg | 进度条预览、雪碧图、WebVTT 与海报 |
| GET | /album/:id/artwork /artist/:id/artwork /person/:id/avatar | 专辑、艺人、人物图片 |
| GET | /media/:id/photo /photo/thumb.jpg /photo/medium.jpg /photo/face/:id/thumb.jpg | 照片预览与人脸缩略图 |
| GET | /media/:id/document/cover.jpg /document/preview.pdf /document/page/:page | 文档封面、PDF 预览与单页图 |
| GET | /media/:id/subtitles/:sid/vtt /media/:id/atrack/:stream/index.m3u8 /atrack/:stream/seg/:seg | 字幕 WebVTT 与分离音轨 HLS |
| GET | /media/:id/forensic/master.m3u8|manifest.mpd|init/:rendition|seg/:rendition/:index|/:rendition/index.m3u8 | 取证播放清单、初始化段与分片 |
| GET | /proxy/image | 按查询参数代理远程图片 |
| GET / POST | /jit/session/:sessionID/*asset /pause /resume /seek /end | 即时转码会话拉流,以及暂停、恢复、跳转、结束。写操作使用幂等键 |
| 方法 | 路径 | 说明 |
|---|---|---|
| GET / POST / PUT / DELETE | /shares/:id /shares/:id/revoke|rotate|rotate-token|regenerate-code|unlock /shares/batch-revoke /shares/batch/revoke /shares/export | 分享详情、修改、删除、撤销、轮换令牌、重设口令、解锁。rotate-token、batch/revoke、export 分别是轮换、批量撤销和 audit.csv 的别名。标准用户,且受分享授权门槛约束 |
| GET / POST / PUT | /admin/shares /admin/shares/stats /admin/shares/:id/revoke /admin/settings/share | 管理端分享列表、统计、撤销和分享设置。未授权时 403 |
| GET | /share/:token/preview|preview/sprite.jpg|preview/thumbs.vtt|poster|lyrics|download /document/preview.pdf|page/:page|cover | 匿名预览、海报、歌词、下载和文档页。仍受分享令牌与口令约束 |
| GET / POST | /share/:token/drm/key /share/:token/drm/widevine/service-cert /share/:token/drm/widevine/license /share/:token/drm/fairplay/cert /share/:token/drm/fairplay/license | 分享令牌下的 AES-128 密钥、Widevine 与 FairPlay。DRM 模块未加载时这些路径不注册 |
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /scan/task/:id/cancel /admin/media/:id/ingest/steps/:step_id/retry | 取消扫描;重试可选的刮削、预览、字幕或预处理步骤 |
| POST / DELETE | /transcode/task/:id/retry /transcode/task/cleanup-failed|cleanup-failed-before | 重试转码,清理失败任务 |
| POST | /preview/task/:mediaId/retry /preview/task/batch | 预览任务重试与批量入队 |
| POST / DELETE | /subtitle/task/:mediaId/reset|retry|cancel|run-now /subtitle/task/:mediaId /subtitle/task/batch|cleanup-failed|cleanup-before | 字幕任务控制、删除与清理 |
| POST | /lyric/task/:mediaId/retry /lyric/task/batch|cleanup-failed|cleanup-before | 歌词任务重试、批量与清理 |
| POST | /atrack/task/:mediaId/retry /atrack/task/batch /keyframe/task/:mediaId/retry /keyframe/task/batch | 音轨与关键帧任务 |
| POST / DELETE | /encrypt/task/:id/cancel|reset /encrypt/task/:id /encrypt/task/batch | 加密任务取消、重置、删除与批量 |
| GET / POST / PUT / DELETE | /schedule/task/:id /schedule/task/:id/run /schedule/task/cleanup-duplicates | 修改、删除、立即运行定时任务,清理重复项 |
| GET / PUT / POST | /scrape/config /scrape/config/test /scrape/task /scrape/task/run /scrape/artwork/backfill /scrape/history /scrape/search /scrape/parse-title /scrape/tmdb/images /scrape/person/search | 刮削配置、测试、任务、历史、检索、标题解析和候选图 |
| POST / DELETE / PATCH / PUT / GET | /media/:id/manual-match /media/:id/match /media/:id/meta /media/:id/images /media/:id/image-candidates /media/:id /media/:id/deletion-plan /media/:id/lyrics /media/:id/lyrics/import /media/:id/subtitles/:sid | 手工匹配与解除、改元数据和图、删除媒体前的删除计划、保存或导入歌词、删除字幕。管理端 PUT /media/:id 更新媒体记录 |
| GET / POST / DELETE | /media/:id/optimization /media/:id/optimization/renditions /media/:id/optimization/renditions/:rid | 单媒体优化产物的查询、提交和删除。属预转码授权门槛 |
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /favicon.svg /favicon.ico | 站点图标,无 /api/v1 前缀,无鉴权 |
| PUT | /admin/branding | 保存品牌名与图标。GET /branding 为公开读取 |
| GET | /admin/overview/stream | 管理概览 SSE。与任务流同在允许查询参数令牌的管理流分组 |
| GET / PUT | /admin/system-logs/settings /runtime /runtime/stream /access /access/:date /access/:date/download | 运行级别与访问日志开关、运行日志快照与 SSE、按天访问日志的列表、查看和下载。流只接受 Authorization: Bearer |
| POST | /admin/system-options/test/asr|ocr|photo-classify|photo-face|doc-trans|docreader /install/asr|ocr|photo-classify|photo-face|doc-trans|docreader|libreoffice | 检测或安装对应本机引擎。路径是 test/ 或 install/ 加引擎名 |
| GET / POST | /admin/watermark/marks /marks/:id /traces | 水印标记列表、单条标记和追踪记录。提取与取证匹配见 4.6 |
| GET / POST | /admin/jit/overview|cost|budget|lifecycle|keys/lifecycle|degradation /lifecycle/run /keys/lifecycle/run | 即时转码概览、成本、预算、生命周期和降级。两个 run 挂了幂等中间件 |
| GET / PUT / PATCH / POST | /admin/scheduler/policy /admin/scheduler/control|explain | 读取、整份保存或局部修改调度策略;控制与解释见 4.6 的合并行 |
| GET / POST / PUT / DELETE | /admin/users /admin/users/:id /admin/users/:id/reset-password | 用户列表、创建、修改、删除和重置密码 |
| GET / POST / PUT / DELETE | /admin/settings/pretranscode-presets/:id …/clone …/toggle …/renditions …/renditions/:rid …/renditions/sort /admin/settings/pretranscode-watermark-image | 预设详情、克隆、开关、档位增删改与排序、水印图。授权门槛 |
| GET / POST / DELETE | /admin/transcode/tasks/:id …/cancel|retry|pause|resume …/renditions/:job_id/cancel|retry /admin/transcode/cleanup-failed | 预转码任务详情与控制、单档取消或重试、清理失败任务 |
| GET / DELETE | /admin/optimization/media/:id/plays …/renditions/:rid …/renditions /admin/optimization/media/:id | 优化媒体的播放次数,以及按档或整片清除产物 |
| PUT / DELETE / POST / GET | /admin/settings/pretranscode-webhooks/:id …/test …/logs | 更新、删除、测试 Webhook 并查看投递日志 |
| POST / DELETE | /admin/transcode/cluster/nodes/:id/drain|resume /admin/transcode/cluster/nodes/:id | 排空、恢复或退役集群节点 |
| 方法 | 路径 | 说明 |
|---|---|---|
| GET / POST | /drm/widevine/service-cert|license /drm/powerdrm/key /drm/hls/aes128/key /drm/hls-key/:taskID /drm/fairplay/cert|license | 播放通道上的许可证与密钥。模块未加载时这些路径不存在 |
| POST / GET | /transcode/drm/repair /admin/drm-license-audit /admin/drm/license/verify | 修复 DRM 产物、许可证审计和校验 |
| GET / POST / DELETE | /admin/license/status /admin/license/file /admin/license/fingerprint | 许可证状态、导入或删除许可文件、机器指纹。由许可证模块注册 |
| POST | /upload-studio/series /upload-studio/series/:id/episodes | 上传工作室创建系列并追加分集。由对应企业模块注册 |
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /jit/master/:fileId | 旧链路主清单。可选查询 max_height。媒体未写入 Redis 时 404,error 为 Video not prepared。响应 Cache-Control: no-store |
| GET | /jit/playlist/:fileId/video/:bitrate /jit/playlist/:fileId/audio/:lang | 视频或音频变体清单。主清单会把本次请求的 access_token 或 Bearer 接到这些 URL 上 |
| GET | /jit/segment/:fileId/video/:bitrate/:segId /jit/segment/:fileId/audio/:lang/:segId | 对应分片 |
| POST | /jit/session/pause|resume|end|seek | 请求头 X-Session-ID 必填。暂停、恢复、跳转在会话不存在时 404;结束会话即使不存在也返回 {"ok":true}。路径里没有会话号,与 /jit/session/:sessionID/… 不是同一套 |
媒体服务在装配了即时调度器时,把上表挂到播放通道(Bearer 或 access_token)。同一组处理函数也可由独立进程(默认 :8300)提供,该入口没有这层鉴权。播放计划默认不指向这些 URL;只有打开 jit.legacy_fallback_enabled 才会。日常即时转码走 /jit/session/:sessionID/…。4.1–4.6 已写出字段的端点不在本节重复。别名只是另一条路由,不改变处理函数。
05响应状态与错误码#
5.1HTTP 状态通用语义
下表为本服务实际使用的 HTTP 状态语义,用于接入方建立统一的分支判断。
| 状态码 | 语义 | 接入方处置 |
|---|---|---|
| 200 | 成功 | 解析业务响应 |
| 201 | 创建成功 | 记录返回的资源标识 |
| 400 | 请求参数缺失或非法 | 修正请求,不应重试 |
| 401 | 未认证 / 令牌无效 | 重新获取令牌后重试 |
| 403 | 无权限 / 令牌作用域不符 / 来源不被允许 | 不应重试,检查权限或来源配置 |
| 404 | 资源不存在或尚未就绪 | 确认标识;若为分片/产物未就绪,可按退避重试 |
| 405 | 方法不被允许 | 修正请求方法 |
| 409 | 状态冲突(配额超限、幂等键冲突等) | 按错误码区分处置,不应盲目重试 |
| 410 | 会话已过期 | 重新建立会话 |
| 413 | 请求体超限 | 拆分或改用分片上传 |
| 429 | 触发限流 | 退避后重试 |
| 500 | 服务端内部错误 | 携带 request_id 反馈,退避后重试 |
| 503 | 服务不可用 / 产能或容量超限 / 功能被关闭 | 按 retryable 判定是否重试 |
5.2统一错误信封与错误码表
形态 A 错误码(播放协议面,结构见 2.3)
| code | HTTP | retryable | 触发条件 |
|---|---|---|---|
| session_expired | 410 | false | 播放会话已过期,需重新建立会话 |
| session_not_found | 404 | false | 会话标识不存在 |
| invalid_asset | 400 | false | 资源路径、档位或分片标识非法 |
| key_scope_mismatch | 403 | false | 密钥作用域与请求来源不匹配 |
| forbidden | 403 | false | 缺少或无效的播放令牌 |
| origin_not_allowed | 403 | false | 请求来源不在允许列表内 |
| asset_unavailable | 404 | false | 清单、初始化段、音轨或分片尚未就绪 |
| segment_not_ready | 202 | true | 分片尚在产出。响应带 Retry-After: 1,details 含 session_id 与 retry_after_seconds=1。即时转码会话还会带 expires_in。按 1 秒退避重试,不要当成失败 |
| key_service_unavailable | 503 | true | 密钥服务暂不可用,可退避重试 |
| capacity_exceeded | 503 | true | 转码产能或缓存容量超限,可退避重试 |
| invalid_idempotency_key | 400 | false | 幂等键格式非法(须 8–128 位) |
| invalid_request_body | 400 | false | 请求体无法读取 |
| request_body_too_large | 413 | false | 幂等请求体超过 1 MiB |
| idempotency_key_conflict | 409 | false | 同一幂等键被用于不同请求体 |
形态 B 业务 reason 码(结构见 2.3,error 为人读信息)
| 域 | reason 码 | 典型触发 |
|---|---|---|
| 鉴权与令牌 | invalid_token | 令牌无效或已失效 |
| user_token_rejected | 用户令牌被策略拒绝 | |
| origin_mismatch | 来源不匹配 | |
| policy_denied | 被安全策略拒绝 | |
| method_not_allowed | 方法不被允许 | |
| maintenance | 系统维护中 | |
| 分享 | share_disabled | 分享功能被管理员关闭 |
| share_not_allowed_for_api_client | 机器令牌不允许创建分享 | |
| share_quota_exceeded | 该媒体活跃分享数超上限 | |
| share_not_found | 分享不存在 | |
| share_not_updatable | 分享状态不可更新 | |
| note_too_long | 备注超过 50 字符 | |
| 分享有效期 | invalid_expires_in | 有效期别名取值非法 |
| invalid_expires_at | 到期时刻非法 | |
| expire_hours_out_of_range | 有效期小时数越界 | |
| expires_exceeds_max_days | 有效期超过允许的最大天数 | |
| allow_never_expiry_disabled | 「永不过期」未被允许 | |
| first_view_out_of_range | 首访有效期取值越界 | |
| 访问口令 | code_required | 需要口令但未提供 |
| code_invalid | 口令非法 | |
| code_locked | 口令因多次失败被锁定 | |
| invalid_access_code | 访问口令校验失败 | |
| 下载与能力 | download_disabled | 该分享未开放下载 |
| download_capability_required | 该媒体类型必须开放下载 | |
| 媒体与资源 | media_missing | 媒体不存在 |
| media_mismatch | 媒体与分享不匹配 | |
| nothing_shareable_for_type | 该类型无可分享入口 | |
| unsupported_media_type | 媒体类型不受支持 | |
| drm_asset_not_ready | 受保护资源尚未就绪 | |
| 系统 | rate_limited | 触发限流 |
| not_in_build | 当前构建未包含该能力 |
上表为实现中已出现的 reason 码全集,随版本演进可能新增;未列出的 reason 一律按不可重试的调用方错误处理并反馈。reason 为空字符串的返回表示未附带机器可读短码,仅读 error。
5.3错误处理与排查约定
- 先分流、后判重试:解析出 code / reason 后,按 2.5 的重试约定分流;只有 retryable = true、429 与 5xx 参与重试。
- 幂等保护:所有重试请求必须携带同一个 Idempotency-Key 与完全一致的请求体,否则会触发 idempotency_key_conflict。
- 追踪对齐:错误响应中的 request_id 与服务端访问日志一一对应。反馈问题时必须附带该标识与调用时刻。
- 缓存禁令:播放协议面错误响应强制 Cache-Control: private, no-store,接入方不得缓存。
- 口令锁定:分享口令连续校验失败会触发锁定(code_locked),须由分享方通过解锁接口恢复。
- 恢复:401 重新登录或换票;403 的授权码改授权或降级功能,不重试;202 segment_not_ready 等待 Retry-After 后取同一分片;429 服从 Retry-After;409 先查询当前资源再决定是否换幂等键。形态 A 用响应里的 request_id 对齐访问日志。没有值班联系人或处理时效;反馈使用第 8 节的公开联系方式,并附文档版本、章节与 request_id。
06系统对接说明#
6.0通用对接框架
每个对接场景按同一组维度描述,便于评审与验收时逐项核对:
| 维度 | 要回答的问题 |
|---|---|
| 系统边界 | 哪些职责由 PowerMedia 承担,哪些由集成方承担,交界在哪 |
| 数据流向 | 数据从哪来、经过哪些环节、最终落到哪 |
| 触发条件 | 什么动作触发处理,前置状态是什么 |
| 状态回调 | 如何得知处理完成或失败,回调与查询如何配合 |
| 异常处理 | 失败后如何判定、重试、补偿与告警 |
| 幂等 | 重复提交是否安全,如何避免重复副作用 |
| 安全校验 | 鉴权、授权、来源校验、审计留痕如何落地 |
6.1上传对接
| 维度 | 约定 |
|---|---|
| 系统边界 | PowerMedia 负责落盘、校验、探测、登记与后续处理编排;集成方负责文件来源、业务归类(目标库/目录)与标题等业务属性 |
| 数据流向 | 集成方 → 上传接口 → 上传暂存/分片目录 → 目标目录落盘 → 媒体记录登记 → 打包 /(视频)即时转码预处理 / 入库后处理 |
| 触发条件 | 上传成功即自动触发,无需集成方二次调起;视频类型额外触发即时转码预处理 |
| 状态回调 | 上传接口同步返回媒体标识;后续处理进度通过任务状态查询与 Webhook 获取(见 6.2、6.5) |
| 异常处理 | 缺文件 400、存储失败 500。上传接口未挂幂等中间件,失败后应先查重再重传。分片用同一 upload_id 覆盖缺失序号即可续传;合并成功才删除分片目录,未合并的目录没有定时清理 |
| 幂等 | 上传接口未挂载幂等中间件;同名重复上传会产生多条媒体记录。建议集成方先调 /upload/dedupe-check 查重,或自行做业务侧去重 |
| 安全校验 | 管理通道 JWT + 管理员角色。没有上传字节上限,扩展名只用于分类、不用于拒绝。详见 4.1 |
6.2转码对接
| 维度 | 约定 |
|---|---|
| 系统边界 | PowerMedia 负责转码编排、档位产出、集群调度与产物清理;集成方负责提交时机、档位选择与结果消费 |
| 数据流向 | 媒体记录 → 转码任务 → 档位作业 → 播放产物 → 播放/分享消费 |
| 触发条件 | 入库后自动触发后处理;亦可经 /transcode/async 或预转码组接口显式提交 |
| 状态回调 | Webhook 事件 rendition.completed / rendition.failed / task.completed / task.failed / run.completed / run.failed;兜底走 /transcode/task/:id/status 与 /admin/transcode/tasks/:id/renditions |
| 异常处理 | 本地步骤默认 1 次尝试,刮削默认 3 次,以行上的 max_attempts 为准;耗尽后状态为 failed,由 reset 或队列 retry 端点重新入队,没有固定秒级退避。播放侧产能不足返回 capacity_exceeded(retryable=true),应退避重试。见 4.3 |
| 幂等 | 转码提交接口未挂载幂等中间件;重复提交可能产生重复任务。集成方须自行去重,或改用统一任务控制面核对既有任务 |
| 安全校验 | 提交走管理通道;状态查询走播放通道。集群管理与预设管理属授权门槛 |
6.3分享对接
| 维度 | 约定 |
|---|---|
| 系统边界 | PowerMedia 负责分享凭证生成、有效期与口令校验、访问审计、下载开关与分享面 DRM 许可;集成方负责分享发起时机、受众管理与链接分发 |
| 数据流向 | 媒体记录 → 分享记录(令牌 / 口令 / 策略)→ 匿名访问面消费 → 访问日志 |
| 触发条件 | 由已认证用户显式创建;机器令牌不可创建。单媒体活跃分享数受限(默认 20) |
| 状态回调 | 33 个 Webhook 事件里没有分享事件。回传途径是 /shares/:id/access-log 与审计导出 /shares/audit.csv |
| 异常处理 | 口令错误累积到阈值(默认 5 次)后锁定(默认 15 分钟,code_locked),由分享方调用解锁接口恢复。撤销与令牌轮换写入数据库后,下一次匿名请求即失效,没有额外延迟 |
| 幂等 | 分享创建接口未挂载幂等中间件;重复调用会产生多条分享记录(并计入配额)。集成方须以媒体 + 受众为键自行去重 |
| 安全校验 | 创建走标准用户组 JWT;访问走分享令牌 + 可选口令;下载受分享开关约束;受保护内容经分享面 DRM 端点取许可 |
6.4AI 媒体处理对接
| 维度 | 约定 |
|---|---|
| 系统边界 | PowerMedia 负责任务编排、引擎调用与结果落位(字幕 / 人脸 / 分类 / 文档解析等);集成方负责提供方配置、额度管理与结果业务化 |
| 数据流向 | 媒体 → AI 任务 → 引擎处理(可能出域)→ 结果落位 → 查询/回传 |
| 触发条件 | 入库后自动触发部分处理(如元数据、字幕);亦可经管理端接口显式触发 |
| 状态回调 | Webhook 事件含 subtitle.obtained/failed、subtitle_recognize.obtained、metadata.obtained 等;兜底走任务查询端点 |
| 异常处理 | 失败事件与重试端点齐备(如 /subtitle/task/:mediaId/retry)。尝试次数与入库步骤相同:本地默认 1 次,刮削默认 3 次,见 4.3 |
| 幂等 | AI 任务提交接口未挂载幂等中间件;重复触发会重复计费与重复处理。集成方须自行去重 |
| 安全校验 | 触发与配置走管理通道;提供方凭据保存在系统配置中,不通过接口回传。出域合规见 4.5 说明 |
6.5Webhook 事件订阅
服务端支持向集成方登记的回调地址主动推送处理事件,是状态回传的主通道。
| 项目 | 约定 |
|---|---|
| 请求方法 | POST |
| 请求体 | 固定五个键:event、knoxMediaId、endpointId(当前恒为 null)、media(事件数据)、event_id。没有 timestamp 字段 |
| 事件标识 | event_id 是不含自身的四字段信封的 SHA-256 前 16 字节,十六进制。同一投递的重试字节不变,接收方据此去重 |
| 媒体标识 | 入库步骤事件的 knoxMediaId 是媒体 id。任务与档位调度器发出的 task.completed / task.failed / rendition.* 把任务 id 放在该字段,同时在 media.task_id 再写一次 |
| 签名请求头 | X-Knox-Signature: sha256=<hex> |
| 签名算法 | HMAC-SHA256,以登记的密钥对请求体原文签名,十六进制小写并加 sha256= 前缀 |
| 投递方式 | 异步投递 |
| 重试策略 | 首次立即投递,非 2xx 或网络错误后再试 3 次,间隔 1 秒、4 秒、16 秒。单次请求超时 10 秒。队列容量 4096、4 个投递协程;队列满时丢掉同一回调、同一事件的最旧一条 |
| 配置与日志 | 管理端可登记、测试、更新、删除回调地址并查阅投递日志(/admin/settings/pretranscode-webhooks…) |
接收方要求
- 校验 X-Knox-Signature:用登记密钥对收到的请求体原文做 HMAC-SHA256,与请求头中的十六进制值做恒定时间比较;不匹配即丢弃并返回非 2xx。
- 按 event_id 幂等去重:同一 event_id 只处理一次,重复投递返回 2xx 即可。
- 尽快返回 2xx:耗时处理应先入队再返回,避免触发服务端重试导致重复投递。
- 对未知事件类型静默忽略并返回 2xx,便于向后兼容新增事件。
- 回调地址建议使用 HTTPS 并置于服务端可达网络内;回调请求本身不携带用户身份。
事件类型清单(33 项,按域归类)
| 域 | 事件类型 | 含义 |
|---|---|---|
| 测试与媒体 | test | 回调连通性测试 |
| media.added | 新媒体入库 | |
| media.visible | 媒体对用户可见 | |
| 任务 | task.completed | 任务完成 |
| task.failed | 任务失败 | |
| 元数据与封面 | metadata.obtained | 元数据提取完成 |
| poster.obtained | 封面生成完成 | |
| 缩略与预览 | thumbnail.obtained | 缩略图生成完成 |
| preview.obtained | 预览生成完成 | |
| 雪碧图与关键帧 | sprite.obtained | 雪碧图生成完成 |
| keyframe.obtained | 关键帧提取完成 | |
| 字幕 | subtitle.obtained | 字幕生成完成 |
| subtitle_recognize.obtained | 字幕识别完成 | |
| 音轨 | atrack.obtained | 音轨提取完成 |
| 加密 | encrypt.obtained | 资源加密完成 |
| 预转码 | pretranscode.completed | 预转码完成 |
| pretranscode.failed | 预转码失败 | |
| 档位 | rendition.completed | 档位产出完成 |
| rendition.failed | 档位产出失败 | |
| 打包 | package.obtained | 打包完成 |
| 刮削 | scrape.obtained | 刮削完成 |
| 批次 | run.completed | 批次运行完成 |
| run.failed | 批次运行失败 | |
| 失败类 | poster.failed | 封面生成失败 |
| thumbnail.failed | 缩略图生成失败 | |
| preview.failed | 预览生成失败 | |
| keyframe.failed | 关键帧提取失败 | |
| subtitle.failed | 字幕生成失败 | |
| atrack.failed | 音轨提取失败 | |
| 失败类(续) | encrypt.failed | 资源加密失败 |
| keyframe_extract.failed | 关键帧提取阶段失败 | |
| subtitle_extract.failed | 字幕提取阶段失败 |
- 另有 atrack_extract.failed(音轨提取阶段失败),合计 33 个事件类型。
- media 对象:入库步骤完成时含 run_id、step、status、finished_at,以及非空的 width、height、bitrate、duration、format。失败时把 error 放进同一对象,不再附媒体尺寸。media.added 含 run_id、title 与上述尺寸字段。run.completed / run.failed 含 run_id、status、error。档位完成含 task_id、job_id、rendition_name;档位失败再加错误文本。
- 没有回调条数上限,也没有来源 IP 白名单。未配置 secret 时不发送 X-Knox-Signature。单次超时 10 秒,见上表。
07版本与更新记录#
| 版本 | 日期 | 状态 | 主要变更 |
|---|---|---|---|
| v0.3.2 | 2026-11-06 | 源码核对版 | 去掉阅读前须知、核对标记与「已确认 · 源码」。正文不再引用源码文件路径 |
| v0.3.1 | 2026-11-06 | 源码核对版 | 去掉核对清单,版本记录与反馈顺延为第 7、第 8 节。补上此前只用省略号带过的端点:收藏与播放列表、资料浏览、播放资源、分享别名与匿名 DRM、任务维护、系统日志具体路径、预转码细项。商业模块未加载时不注册许可证、DRM 与上传工作室路由。另列播放通道上的 Redis 旧即时转码路由 /jit/master、/jit/playlist、/jit/segment 与无会话号的暂停/恢复/结束/跳转;独立进程默认 8300 提供同一组处理函数且不挂鉴权,播放计划仅在 jit.legacy_fallback_enabled 打开时指向它们。库内播放在进程内会话选择 DASH 时 mode 为 jit_dash。API 客户端吊销更正为 DELETE /api/v1/admin/api-clients/:id |
| v0.3.0 | 2026-11-06 | 源码核对版 · 待补充项已关闭 | 按实现关闭 TBD-001 至 TBD-017:补充分片、入库与任务状态、静态前缀、播放字段、分享创建与匿名面、登录与分页、端点限额、授权 403、Webhook 信封。修正 segment_not_ready 为 202 且可重试;删除载荷中并不存在的 timestamp。写明源码未定义保留期限、处理时效与值班联系人 |
| v0.2.0 | 2026-11-06 | 草案 · 源码核对版 | 依据服务端实现全面重写:新增鉴权四通道与令牌属性(2.2)、两套错误响应形态(2.3)、限流阈值(2.4)、幂等语义与专属错误码(2.5);API 参考改为按鉴权通道 + 功能域索引,写实 6 域端点并补全上传、分享创建、外部播放计划的请求/响应字段(4.1 / 4.2 / 4.4);错误码表按实现归纳形态 A 全表与形态 B reason 全集(5.2);新增 Webhook 事件订阅章节含签名、重试与 33 项事件清单(6.5);对接七维标注已核对与待确认项;待补充清单重整为 17 条 |
| v0.1.0 | 2026-11-06 | 草案 · 框架版 | 建立文档结构与填写规范:九章骨架、目录导航、版本标识、占位标记约定、API 条目七维规范、对接七维框架、待补充清单与更新记录模板。全部接口与流程以占位标注,不作推测 |
08反馈与文档获取#
本页为公开核对版,已关闭条目可直接对接。每个端点的完整调用示例仍以交付版文档包为准。反馈时请注明文档版本、章节编号,并附上错误响应中的 request_id(形态 B 没有该字段时改附请求路径与时间)。
没有规定勘误处理时效、对接窗口或内部责任分工。反馈使用上面的公开联系方式;本页不另写组织承诺。