声音巴士开放 API v1 文档 - 声音巴士

本文概述声音巴士开放 API v1 的当前兼容契约。机器可读且具有约束力的完整定义请参阅 OpenAPI v1 规范；当本文与规范存在差异时，以该规范及线上响应为准。

接口范围

• 当前共有 40 个规范路径、42 个操作，其中 23 个 GET、19 个 POST；HEAD 和 OPTIONS 是隐式协议行为，不计入 42 个操作。
• 其中 22 个匿名公开读取可在不登录时调用。其余接口按规范要求登录、管理权限或版主权限。

认证、CSRF 与跨域

• 认证优先级固定为 Cookie token、任何显式 Authorization、POST 请求体 token。显式 Cookie token 即使为空也会阻止低优先级回退；显式 Authorization 即使为空、格式错误或不是唯一有效的 Bearer token，也会阻止请求体 token 回退并按未登录处理。
• 仅接受当前 v1 会话；历史固定 token 已退场。使用 Cookie 发起写请求时必须携带 CSRF 保护；不携带 Cookie 的 Bearer 或请求体 token 客户端不使用浏览器 Cookie CSRF 流程。
• 匿名公开 GET/HEAD 可按公开 CORS 读取。带凭证的读取以及所有写操作均不向任意外部 Origin 开放。

请求大小与分页

• 普通 API 的完整请求体上限为 1 MiB。节目创建和更新的完整请求体上限为 110 MiB，其中音频 upload_file 单文件上限为 100 MiB；该规则不改变媒体存储位置或文件处理流程。
• page 取值 1–100000；limit 与 pagesize 取值 1–100。若 limit 和 pagesize 同时提供，两者必须相等。

读取副作用与兼容响应

• 隐式 HEAD 返回与 GET 一致的状态、内容类型和确定的 Content-Length，但正文为空且不产生业务副作用。
• GET /api/v1/program/item 会增加 play_count；GET /api/v1/article/item 对普通数据库文章会增加 view_count；GET /api/v1/pm/list 在 type=to 时会清除对应未读计数。使用 HEAD 不会触发这些变化。
• 部分历史业务失败为了兼容旧客户端仍可能返回 HTTP 200，并通过 code=0 与 data 表达失败；调用方应同时检查 HTTP 状态和响应中的 code。

已经退场的操作

以下 7 个操作不属于当前 v1，请勿继续调用：

• POST /api/v1/program/delete
• POST /api/v1/comment/update
• POST /api/v1/comment/delete
• GET /api/v1/tag/recommend
• GET /api/v1/album/hot
• POST /api/v1/pm/delete
• POST /api/v1/pm/truncate

请求字段、响应结构、错误码、权限和每个操作的详细说明均以 OpenAPI v1 规范为准。