首页/技术文档
文档状态 · 源码核对版 DOC v0.3.2

开发者文档

面向集成方、实施与运维人员的接口参考与系统对接说明。接口路径、字段、状态码与流程可直接对接。接口未规定的组织时效与合规策略,正文直接说明。

文档版本v0.3.2
文档状态源码核对版
适用产品版本PowerMedia 服务端
最后更新2026-11-06
维护责任方见第 8 节公开联系方式

01文档说明#

1.1适用范围与读者

本页面向需要与 PowerMedia 智能媒体服务器进行系统集成或二次开发的技术人员,覆盖以下读者:

  • 集成方开发人员:需要调用上传、查询、播放授权、分享与任务类接口完成业务系统对接。
  • 实施与运维人员:需要了解鉴权模型、限流阈值、状态机流转、回调机制与异常处理约定。
  • 测试与验收人员:需要依据状态码、错误码与幂等语义设计用例并核对结果。

本页不覆盖产品功能说明与部署拓扑,相关内容见 产品能力、技术规格 与 内容保护。

1.2版本与状态标识

文档版本采用三段式编号,独立于产品版本演进:

版本号语义MAJOR.MINOR.PATCH
字段含义变更触发
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/loginJSON:username、password,均为必填200:token(JWT)、expires_in_hours(默认 168)缺字段 400;账号或密码错误 401 {"error":"invalid credentials"}
POST /api/v1/oauth/tokenJSON 或表单:grant_type=client_credentials、client_id、client_secret200: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请求与响应通用结构

请求头通用项

通用请求头均可选,除标注外
请求头类型必填说明
Authorizationstring条件必填Bearer <JWT>;公开端点与分享匿名面除外
Content-Typestring条件必填有请求体时必填;上传用 multipart/form-data
Idempotency-Keystring可选写操作幂等键,见 2.5;格式 [A-Za-z0-9._:-]{8,128}
X-Request-Idstring可选调用方侧追踪标识;服务端会在响应中回填自身 request_id,用于对齐访问日志

错误响应信封 服务端存在两套并行的错误响应形态,接入方必须同时处理,不可只解析其一。

形态 A · 统一错误信封(播放协议面)code + message + request_id + retryable + details
{
  "code": "session_expired",
  "message": "session expired",
  "request_id": "…",
  "retryable": false,
  "details": null
}
形态 B · 简洁错误对象(业务管理面)error + 可选 reason
{
  "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 语义
项目约定
请求头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。

请求字段multipart/form-data
字段类型必填说明
filefile必填上传文件本体;缺失时返回 400 {"error":"file required"}
library_idint可选目标媒体库标识;缺省时按上传目标目录解析
target_dirstring可选目标目录;与 library_id 共同决定落盘位置
titlestring可选媒体标题;缺省时取上传文件名
响应字段200 OK
字段类型含义
idint新媒体记录标识
file_idstring文件标识
pathstring文件落盘路径;命中去重时指向既有物理文件
md5string文件 MD5
dedupedbool可选。命中感知哈希去重时返回 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/:keyIDHLS 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/hlsHLS 信息播放
GET/api/v1/media/:id/hls/*assetHLS 清单与分片播放
GET/api/v1/media/:id/dash/*assetDASH 清单与分片播放
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。

响应字段200 OK · application/json
字段类型含义
modestring播放模式,固定为 jit_hls
play_urlstring可直接播放的地址
hls_masterstringHLS 主清单地址(与 play_url 同值)
session_idstring播放会话标识
expires_inint剩余有效秒数
expires_attimestamp会话到期时刻,RFC 3339
profile_versionstring输出配置版本
renditionstring本次选定的档位名
degradationobject降级状态,含 level 等;随响应头 X-Degradation-Level 同步下发
capabilitiesobjectadaptive / seek / resume / drm
p2pobjectP2P 能力,当前恒为 {"enabled": false}
sourceobject源信息:duration_ms / width / height
cacheobject缓存命中信息(含 hit / served_from_cache)
compatibilityobjectdirect_play(恒为 false)、source_video、output_profile、profile_reused;被拒绝复用时另含 profile_invalidated
encryptionobject可选。仅受保护内容返回,否则不出现
接口独立限额
限制项默认值说明
计划请求频率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。

请求字段application/json
字段类型必填说明
media_idint条件必填媒体标识;可由路径参数 :id 提供。两者皆缺时返回 400
expire_hoursint可选有效期小时数;缺省取默认值,-1 表示永不过期
expires_instring可选有效期别名:60m / 24h / 7d / never / first_view_24h。与 expire_hours 二选一,非法取值返回 reason=invalid_expires_in
expire_after_first_view_minutesint可选首次访问后多少分钟过期;expires_in 使用 first_view_24h 时由服务端换算写入
use_access_codebool可选是否启用访问口令
enable_codebool可选别名,等价于 use_access_code,同时提供时以后者为准
access_codestring条件必填访问口令;启用口令时提供
allow_downloadbool可选是否允许下载
autoplaybool可选是否自动播放,仅对音视频生效;缺省为 true
notestring可选备注,去除首尾空白后不超过 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 位熵)。撤销或轮换后,下一次匿名请求按库中当前哈希校验,没有额外的失效延迟。
端点索引 · 分享匿名访问面 /api/v1/share/:token
方法路径(相对分享前缀)用途
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/keyHLS AES-128 密钥
GET/drm/widevine/service-certWidevine 服务证书
POST/drm/widevine/licenseWidevine 许可
GET/drm/fairplay/certFairPlay 证书
POST/drm/fairplay/licenseFairPlay 许可
内容保护能力矩阵
方案默认状态说明
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 服务提供方配置、刮削与元数据补全、字幕 / 歌词 / 文档解析、照片人脸与分类等智能处理。本机引擎可离线运行;只有打开的刮削站点或大模型提供方才会把文本发到服务之外。

端点索引 · AI 媒体处理
方法路径用途权限
GET/api/v1/ai-providerAI 提供方列表管理
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人脸缩略图播放
AI 引擎配置与测试
能力域配置 / 测试端点
语音识别(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/tokenOAuth2 令牌签发公开
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-clientsAPI 客户端列表管理
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上传工作室创建系列并追加分集。由对应企业模块注册
Redis 旧即时转码路由播放通道;独立进程另见说明
方法路径说明
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 状态语义,用于接入方建立统一的分支判断。

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
codeHTTPretryable触发条件
session_expired410false播放会话已过期,需重新建立会话
session_not_found404false会话标识不存在
invalid_asset400false资源路径、档位或分片标识非法
key_scope_mismatch403false密钥作用域与请求来源不匹配
forbidden403false缺少或无效的播放令牌
origin_not_allowed403false请求来源不在允许列表内
asset_unavailable404false清单、初始化段、音轨或分片尚未就绪
segment_not_ready202true分片尚在产出。响应带 Retry-After: 1,details 含 session_id 与 retry_after_seconds=1。即时转码会话还会带 expires_in。按 1 秒退避重试,不要当成失败
key_service_unavailable503true密钥服务暂不可用,可退避重试
capacity_exceeded503true转码产能或缓存容量超限,可退避重试
invalid_idempotency_key400false幂等键格式非法(须 8–128 位)
invalid_request_body400false请求体无法读取
request_body_too_large413false幂等请求体超过 1 MiB
idempotency_key_conflict409false同一幂等键被用于不同请求体

形态 B 业务 reason 码(结构见 2.3,error 为人读信息)

业务 reason 码按域归类
域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 媒体处理对接

AI 处理对接 · 七维
维度约定
系统边界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 <登记的回调地址>
项目约定
请求方法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 项,按域归类)

事件类型type
域事件类型含义
测试与媒体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.22026-11-06源码核对版 去掉阅读前须知、核对标记与「已确认 · 源码」。正文不再引用源码文件路径
v0.3.12026-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.02026-11-06源码核对版 · 待补充项已关闭 按实现关闭 TBD-001 至 TBD-017:补充分片、入库与任务状态、静态前缀、播放字段、分享创建与匿名面、登录与分页、端点限额、授权 403、Webhook 信封。修正 segment_not_ready 为 202 且可重试;删除载荷中并不存在的 timestamp。写明源码未定义保留期限、处理时效与值班联系人
v0.2.02026-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.02026-11-06草案 · 框架版 建立文档结构与填写规范:九章骨架、目录导航、版本标识、占位标记约定、API 条目七维规范、对接七维框架、待补充清单与更新记录模板。全部接口与流程以占位标注,不作推测

08反馈与文档获取#

本页为公开核对版,已关闭条目可直接对接。每个端点的完整调用示例仍以交付版文档包为准。反馈时请注明文档版本、章节编号,并附上错误响应中的 request_id(形态 B 没有该字段时改附请求路径与时间)。

电话010-62129317
邮箱marketing@powercom.net.cn
官网www.powercom.net.cn

没有规定勘误处理时效、对接窗口或内部责任分工。反馈使用上面的公开联系方式;本页不另写组织承诺。