REST API

Rust-Srec 在 /api 下提供 JSON REST API。运行中的后端会为其准确构建版本生成权威 OpenAPI 文档。

• Docker 默认地址：Swagger UI 与 OpenAPI JSON
• 使用 rust-srec/.env.example 的源码环境：把以上链接中的 12555 改为 8080

Swagger 属于正在运行的 Rust-Srec 后端，并不位于 docs.srec.rs 文档域名下。

认证

大多数路由要求 Authorization: Bearer <token> 请求头。登录会返回短期访问令牌和有效期更长、会轮换的刷新令牌。

首次登录

初始账号为 admin / admin123!，在调用其他受保护接口前必须修改密码。

curl -X POST http://localhost:12555/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123!","device_info":"API quickstart"}'

响应包含以下字段：

{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_expires_in": 604800,
  "roles": ["admin"],
  "must_change_password": true
}

使用返回的访问令牌替换默认密码：

curl -X POST http://localhost:12555/api/auth/change-password \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"current_password":"admin123!","new_password":"<unique-new-password>"}'

然后使用新密码重新登录，并使用新的访问令牌。must_change_password 为 true 时，其他受保护路由会返回 403 PASSWORD_CHANGE_REQUIRED。

调用受保护接口

curl http://localhost:12555/api/streamers \
  -H "Authorization: Bearer <access-token>"

刷新与撤销

POST /api/auth/refresh 接收 {"refresh_token":"..."}，在同一登录会话内轮换 令牌对。保存替换后的刷新令牌，并串行发送刷新请求，包括来自其他标签页的请求。 重放已消耗的令牌通常会撤销该用户的全部会话；详见重用策略。

POST /api/auth/logout 使用相同请求体，仅撤销该会话的访问令牌与刷新令牌。 也可以在 Authorization 请求头中发送当前会话的 JWT：如果刷新令牌记录已被清理， 服务端仍可撤销该 JWT 自身的会话。提供请求头时凭据必须有效，API 密钥不能充当 这个可选的会话凭据。已认证的 POST /api/auth/logout-all 会撤销该用户全部会话。 修改密码会原子撤销已有会话，需要重新登录；成功导入配置同样会撤销登录会话与 刷新令牌。

升级到绑定会话的 JWT 后，未绑定会话的旧访问令牌会被拒绝。使用仍有效的旧刷新 令牌换取新令牌对，或重新登录。GET /api/auth/sessions 仍列出有效的刷新令牌记录： 轮换后 ID 可能改变；刷新令牌已到期或已清理的会话即使访问令牌仍有效，也可能 不在列表中。

媒体、流代理以及下载/日志 WebSocket 路由优先使用 Authorization 请求头，仅在 缺少该请求头时使用 ?token=；无效或格式错误的请求头不会回退到查询参数。 只读 API 密钥可读取健康详情和录制媒体；下载/日志 WebSocket、流代理和日志配置/ 归档路由需要完全权限密钥。详见 API 密钥与 MCP。

访问令牌、刷新令牌、Cookie 和平台凭据都应按敏感信息处理，不要写入日志或源代码仓库。

路由分组

前缀	用途	认证
/api/health	存活、就绪与依赖状态	混合；启用认证时仅 /live 公开
/api/auth	登录、刷新、退出、改密与会话	混合；以 Swagger 为准
/api/streamers	主播增删改查、检查、过滤器与批量操作	Bearer 令牌
/api/config	全局/平台配置与备份导入导出	Bearer 令牌
/api/templates	可复用配置模板	Bearer 令牌
/api/engines	下载引擎实例	Bearer 令牌
/api/sessions	录制会话	Bearer 令牌
/api/pipeline	工作流、任务、预设、执行与产物	Bearer 令牌
/api/notifications	通知渠道、订阅、偏好与事件	Bearer 令牌
/api/credentials	账号凭据配置、选择状态、验证、刷新与二维码登录	Bearer 令牌
/api/proxies	已保存的代理、连通性测试和生效的代理设置	Bearer 令牌；API 密钥需 full 权限
/api/parse	URL 与元数据解析	Bearer 令牌
/api/downloads、/api/logging、/api/media、/api/stream-proxy	实时或媒体访问	因路由而异；查看 Swagger

请求和响应字段应以生成的 OpenAPI 文档为准，不要仅根据本页摘要猜测。

平台、模板和主播的写入请求用 credential_selection 对象选择账号，其中引用 /api/credentials 中的凭据配置。平台和模板配置中旧的 cookies 字段会以 422 COOKIES_REPLACED 被拒绝。

代理

/api/proxies 管理代理设置所引用的已保存代理。所有请求（包括读取）都要求 API 密钥具有 full 权限。响应会显示代理的 username 以及是否保存了密码（has_password），但从不返回密码。

请求	用途
GET /api/proxies	列出已保存的代理及 usage_count，即选用各代理的设置数量
GET /api/proxies/{id}	单个代理及其 references：选用它的全局设置、平台、模板、主播和账号
POST /api/proxies	按 name、url（http、https、socks5 或 socks5h，写成 scheme://host[:port]）以及可选的 username 和 password 创建
PATCH /api/proxies/{id}	携带 expected_version 编辑。省略 password 会保留原密码；"username": null 会移除登录信息。
DELETE /api/proxies/{id}	删除，可附带 expected_version 查询参数
POST /api/proxies/test	通过已保存的代理（proxy_id，可附带修改后的字段）或未保存的 url，请求一次某个 platform 的首页或 target_url。返回 ok、status、latency_ms 和 error 类型；时限为 10 秒。
GET /api/proxies/system	服务器启动时检测到的环境变量代理，不含登录信息
GET /api/proxies/effective	某个作用域当前的连接方式以及由哪项设置决定：scope_type（global、platform、template、streamer 或 account）、scope_id，模板还可附带 platform_id

冲突返回 409，代码为 PROXY_NAME_TAKEN、PROXY_DUPLICATE（另一个代理的地址和用户名相同）、PROXY_STALE_VERSION，或删除仍在使用的代理时返回 PROXY_REFERENCED，并在 details.references 中列出使用者。地址或登录信息无效时返回 422 PROXY_INVALID。

全局、平台、模板、主播和账号的写入请求用 proxy_route 对象选择代理。旧的 proxy_config 字段会以 422 PROXY_CONFIG_REPLACED 被拒绝。

创建响应与任务进度

创建主播、模板、引擎、过滤器、通知渠道、任务预设、管道预设和管道时，接口返回 201 Created，响应体仍是已创建资源的 JSON。克隆模板和任务预设也会返回 201 及新资源。客户端应接受成功的 2xx 状态，不应要求所有 JSON 响应都必须是 200。

生成的 OpenAPI 文档现已包含会话分段列表、模板克隆，以及浏览器 Web Push 的 四个操作（公钥、订阅列表、订阅和取消订阅），并包含对应的请求与响应结构。

任务列表、任务详情和管道创建响应中的任务摘要使用 progress: null 表示该响应 没有可用进度，这不表示完成了零百分比。请使用 GET /api/pipeline/jobs/{id}/progress 获取最近的处理器专用进度快照； 没有快照时，该接口返回 404。快照中可选的 phase 在 FFmpeg 写完最后一帧后重写 输出时，以及 rclone 上传发送完所有字节、等待目标确认文件时，为 finalizing； 在上传等待重试时为 retrying；在 BaiduPCS 或 rclone 上传正在处理的文件都还没有 发送数据时（包括 rclone 在首次传输前列出目标位置期间）为 preparing（遇到未知的 值时按正常处理对待）。current_file 给出正在处理的文件名，不含目录。 上传首次尝试失败后，attempt 和 max_attempts 给出它在本次任务运行内的尝试 次数，与任务的重试次数无关。

GET /api/pipeline/dag/{id} 为每个步骤返回 job_status、started_at 和 retry_after，时间均为 epoch 毫秒。不会再执行自动重试时，retry_after 为 null，已取消或已失败的工作流也是如此。每个步骤的 progress 是其运行中任务的 快照，与 GET /api/pipeline/jobs/{id}/progress 返回的相同，但 raw 始终为 null。只有步骤的任务正在运行且已上报进度时，步骤的 progress 才有值，因此 null 不表示完成了零百分比。

GET /api/pipeline/dag/{id}、GET /api/pipeline/dags 和 GET /api/pipeline/dag/{id}/stats 中的 progress_percent 将每个已完成的步骤完整计入， 运行中的步骤按其上报的进度计入。失败、已取消和等待中的步骤不计入， 因此失败或已取消的工作流会显示其已完成的部分。对于不存在的工作流， GET /api/pipeline/dag/{id}/stats 返回 404。

搜索筛选

管道任务、录制会话、媒体产物、通知事件、任务预设和管道预设的 search 参数按字面子串匹配。%、_ 和 \ 都是普通字符，不是搜索通配符或转义语法。 例如，audio_extract 不会匹配 audioXextract，% 只会找到含百分号的值。 按输入原样发送搜索文本，并对查询参数进行正常 URL 编码即可，无需额外转义。

ASCII 字母不区分大小写，非 ASCII 字符保留 SQLite 原有的大小写敏感行为， 因此 Ä 与 ä 仍是不同字符。会话标题和通知内容仍搜索存储的 JSON 文本， 包括字段名及 JSON 转义。搜索会与接口的其他筛选条件共同生效，结果总数和 媒体大小汇总也使用与列表分页相同的匹配规则。

错误

API 错误使用统一结构：

{
  "code": "VALIDATION_ERROR",
  "message": "便于阅读的错误说明",
  "details": {}
}

没有额外信息时会省略 details。常见状态为：400 输入无效、401 凭据缺失或过期、403 账号禁用或要求改密、404 资源不存在、409 冲突、422 校验失败、429 登录失败次数过多、500 内部错误、503 依赖不可用。

POST /api/auth/login 会按账号和来源地址分别限流。同一账号连续五次失败后返回 429，code 为 TOO_MANY_REQUESTS，并在 Retry-After 响应头中给出需要等待的秒数；登录成功会立即清零该账号的计数。另有一个宽松得多的按来源地址配额（每窗口 100 次），用于限制密码哈希开销。

来源地址取自 TCP 连接的对端，且不信任 X-Forwarded-For 与 X-Real-IP，因此在本项目自带的前端容器、nginx 或任何反向代理之后，所有登录都会被归到代理的地址上——按地址的配额是开销上限，而不是针对某个客户端的锁定。超过 128 个字符的用户名会在两个配额生效之前直接返回 400（按字符而非字节计算，非拉丁文名称不会因此吃亏）。导入配置时也会应用同一限制，避免导入出无法登录的账号。两个配额均可配置，详见配置。

客户端应根据 HTTP 状态和 code 分支，不要解析面向用户的 message 文本。

兼容性与部署

POST /api/parse/batch 每次最多接受 100 个 URL；DELETE /api/sessions/batch 每次最多接受 100 个会话 ID。超限数组会在处理任何项目之前返回 422，更大的任务 应拆成多次请求；空数组仍有效。登录设备描述在日志和新存储的令牌中最多保留 256 个 Unicode 字符。刷新也会限制旧令牌继承的描述，但不会批量重写已有数据行。

内部数据库、文件系统、已存储 JSON 和凭据错误会返回通用消息，不再嵌入后端诊断。 安全的请求校验消息仍保持可读性。凭据刷新保留既有的 400 状态及 requires_relogin 提示。

v0.5 API 路径没有版本前缀。请固定后端镜像或二进制版本，把配套 OpenAPI JSON 与生成客户端一同保存，并在升级前测试。破坏性行为会记录在发布说明中。

网络部署应在反向代理处终止 TLS、限制 API 访问来源，非必要时不要公开 Swagger。参见安全和生产部署。