认证与范围
同一站点使用 /api；生产完整前缀为 https://www.murphy-box.com/api。
JSON 响应使用 snake_case，请求字段按下表填写，不自动转换。
| 方式 | 请求头 | 可读范围 |
|---|---|---|
| API Key | X-API-Key: <api-key> | 当前为全量服务身份，包含组织资源，没有逐 Key 组织范围。 |
| 账号 JWT | Authorization: Bearer <token> | admin 全部；org_admin 公共与本库；其他账号仅公共。 |
API Key 由管理员创建。JWT 通过 POST /api/auth/login 获取，有效期 24 小时；系统没有自助注册。
两种凭据同时发送时先验证 Bearer，失败不回退 API Key。“公共资源”也需要认证。
curl 'https://www.murphy-box.com/api/app/audios?page=1&limit=20' \
-H 'X-API-Key: <api-key>'示例使用占位值。不要将真实 Key、JWT 或签名 URL 写入源码、日志或文档。
查询接口
以下路径均以 /api/app 为前缀。只有 status 与 docs 免认证。
列表默认 page=1&limit=20，limit 最大 100；分页结构为 pagination { page, limit, total, pages }。
| 方法 | 路径 | 参数与返回 |
|---|---|---|
| GET | /status | 服务开关、API 版本和总体统计，免认证。 |
| GET | /docs | 当前路由元数据索引，免认证；完整合同见仓库文档。 |
| GET | /categories | include_stats=true；返回 categories[] 树，同级自然排序。 |
| GET | /categories/:id | 返回 category，含父目录与直属音频数。 |
| GET | /categories/:id/audios | 仅直属音频；page、limit、sort、order；返回 category、audios、pagination。 |
| GET | /audios | category_id、search、page、limit、sort、order；返回 audios、pagination。 |
| GET | /audios/:id | 返回 audio，可选版本。 |
| POST | /audios/batch | JSON {"ids":["<id>"]}，1–100 个且不重复；返回 audios、found、requested。 |
| GET | /audios/:id/url | 可选版本与 expires；返回 audio、urls.public、urls.signed、expires_in、expires_at。 |
| GET | /audios/:id/stream | 可选版本；返回 302 跳转，不由 AUR 代理字节流。 |
| GET | /search | 必填 q，可选 category_id、page、limit；返回 query、audios、pagination。 |
| GET | /recent | limit 默认 10、最大 50，可选 category_id；返回 audios。 |
| GET | /stats | 当前身份可见资源的音频、目录与存储统计。 |
sort 可选 created_at / title / duration / size，order 可选 asc / desc，默认按上传时间倒序。
批量详情按请求顺序返回可见项，缺失项省略；它没有 MS 接口的 missingIds 字段。
播放与版本
持久保存 audio_id，播放前请求 URL。签名默认 3600 秒，expires 最大 86400 秒；到期重新获取。
时间单位为秒，大小为字节，bitrate 为 bps，sample_rate 为 Hz。
curl 'https://www.murphy-box.com/api/app/audios/<audio-id>/url?bitrate_kbps=48' \
-H 'X-API-Key: <api-key>'bitrate_kbps=48|64|96 与 version_id=<version-id> 互斥；
version_id=source 选原版。详情、URL 与单条流媒体入口支持选版，批量接口返回默认版本。
不传参数使用系统当前指针，临时选版不修改指针。
available_versions[] 只包含成功版本，包含规格、大小、时长、内容摘要、is_default 和 playback_url。
新上传在首次转码完成前可播放原版。历史记录若禁止原版且无可用版本，播放入口返回 409；列表项仍应保留。
删除后全部版本不可见，恢复时一并恢复。
| 方法 | 完整路径 | 行为 |
|---|---|---|
| GET | /api/stream/:id | 默认 mode=redirect 返回 302；mode=proxy 代理音频并支持 Range。 |
| GET | /api/stream/:id/redirect | 302 跳转至所选版本。 |
| GET | /api/stream/:id/url | 返回 audio、url、expires_in、expires_at；此处字段为 url。 |
| POST | /api/stream/batch | JSON ids（最多 100 且不重复）、可选 expires；返回 urls、found、requested、有效期。 |
| HEAD | /api/stream/:id | 无响应体，按 GET 的认证与选版规则处理，客户端须处理重定向。 |
原生 audio 标签不能自行添加上述认证请求头；先用有认证的请求获取签名 URL，再交给播放器。 私有桶的普通对象地址不保证可直接播放。若签名地址为空，保留业务引用并处理不可用状态。
错误与开关
普通错误含 error，可能另有 message、error_code、request_id。成功结构按接口返回，不统一包在 data 中。
| HTTP | 含义 |
|---|---|
| 400 | 参数错误，例如重复 ID、互斥选版参数。 |
| 401 / 403 | 认证无效 / 身份或来源不允许。 |
| 404 | 不存在、已删除、超出范围或所选版本不存在；不能单凭 404 推断明确删除。 |
| 409 | 没有可用播放版本或其他状态冲突。 |
| 429 | 触发限流。 |
| 500 / 503 | 服务异常 / API 关闭或依赖暂不可用，不能据此删除业务引用。 |
status/docs 不受全局 API 开关影响，但受自身端点开关控制。业务限流默认关闭，开启默认 300 次/15 分钟； 登录与改密共用的 IP 保护始终开启，默认 50 次/15 分钟。
内网边界
MROS 与 MS 入口仅供后端调用，采用固定来源 IP，不用 API Key，不能直接交给浏览器或移动端。
| 接口族 | 合同区别 |
|---|---|
/api/internal/mros | 镜像本页 app 的 13 个只读方法；snake_case，分页最大 100，共用 app 开关。 |
/api/internal/ms/audio | 独立 camelCase 合同；普通分页最大 500，批量详情最大 100，同步分页最大 1000；默认关闭。 |
MS 的完整快照、删除墓碑、游标恢复与历史对象键合同见仓库 API 文档第 15.2 节。 接口实现和单次连通性探测不等于消费者已完成持续同步验收。