音乐服务

音乐聚合能力：爱听音乐网抓取（首页/歌手/歌曲/搜索）与小影音乐自有曲库的增删改查。当前接入 2 条线路。

/api/music/

服务说明

音乐服务聚合两条线路：爱听音乐网（2t58）提供首页榜单、歌手、歌曲详情、播放链接与歌词、关键词搜索，适合直接搭建在线音乐搜索与播放页面；小影音乐是平台自有曲库，提供音乐与播放源的增删改查，以及 JSON 批量导入、导出。

两条线路均需项目签名。2t58 线路的数据来自外部站点实时抓取，播放链接可能带时效，不建议在客户端长期缓存。

小影音乐的导入接口单文件不超过 10MB、单次不超过 9999 条，且不做去重；导出接口在结果超过 9999 条时返回一个 zip 压缩包（内含多个分片 json），可直接回灌导入。

爱听音乐网 2t58

2t58.com 网页抓取（只读）需签名

抓取热门/歌手/歌曲/搜索数据。url 参数必须为 2t58.com 域名地址。

GET /api/music/2t58/home 累计调用 0 次

首页数据

返回热门歌手、歌曲飙升榜、流行趋势榜三个模块。

GET /api/music/2t58/singer 累计调用 0 次

歌手详情

歌手基本信息 + 歌曲列表（含分页）。

歌手页 URL *

2t58.com 歌手歌曲列表页完整地址（必填）

GET /api/music/2t58/song 累计调用 0 次

歌曲详情

歌曲基本信息 + 播放链接 + 歌词 + 每日推荐。

歌曲页 URL *

2t58.com 歌曲详情页完整地址（必填）

GET /api/music/2t58/search 累计调用 1 次

搜索音乐

按关键词搜索歌曲（分页）。

关键词 *

搜索关键词（必填）

页码

选填：页码，正整数，默认 1

小影音乐

自有曲库（Music/MusicSource 数据）需签名

音乐与其播放源的 RESTful 增删改查；音乐详情接口会同时返回其全部播放源。

GET /api/music/xiaoying/musics 累计调用 0 次

音乐列表查询

按关键词/在线状态查询音乐（分页）；不传 online 时默认只返回在线音乐。

关键词

选填：匹配音乐名称/歌手

在线状态

选填：true/false

页码

选填：默认 1

每页条数

选填：1-100，默认 10

POST /api/music/xiaoying/musics 累计调用 0 次

创建音乐

新建一条音乐，返回 music_id（UUID），供详情/播放源关联使用。

音乐名称 *

音乐名称（必填）

歌手 *

歌手（必填，至少一位）

多值写法：多个歌手用逗号或换行分隔（服务端会按多次传参拆成歌手列表）

在线状态

选填：默认 true

去重规则：同名且同歌手（忽略顺序、大小写与首尾空格）视为重复，返回 20031；名称相同但歌手不同（多/少/换歌手）可正常入库。

GET /api/music/xiaoying/musics/<uuid> 累计调用 2 次

获取音乐详情

按音乐 UUID 查询单条音乐，同时返回其全部播放源（music_sources）。

音乐 UUID *

路径参数：音乐 UUID（文档页代调时请替换 URL 中的 <uuid>）

PATCH /api/music/xiaoying/musics/<uuid> 累计调用 2 次

更新音乐

部分字段更新音乐（singer 为整体替换）。

音乐 UUID *

路径参数：要更新的音乐 UUID

音乐名称

选填：新名称

歌手

选填：整体替换歌手列表

多值写法：多个歌手用逗号或换行分隔（服务端会按多次传参拆成歌手列表）

在线状态

选填：true/false

去重规则：更新后若与他条「同名且同歌手」会返回 20031（排除自身）；只改名称或只改歌手到不冲突的组合均可正常更新。

DELETE /api/music/xiaoying/musics/<uuid> 累计调用 2 次

删除音乐

按 UUID 删除音乐（其播放源级联删除）。

音乐 UUID *

路径参数：要删除的音乐 UUID

POST /api/music/xiaoying/music_sources 累计调用 0 次

创建播放源

给某首音乐新增一个播放链接。

音乐 UUID *

音乐 UUID（必填，须已存在）

播放链接 *

播放地址（必填，需合法 URL）

PATCH /api/music/xiaoying/music_sources/<uuid> 累计调用 0 次

更新播放源

部分字段更新播放源（music_id/url）。

播放源 UUID *

路径参数：播放源 UUID

播放链接

选填：新播放地址

DELETE /api/music/xiaoying/music_sources/<uuid> 累计调用 0 次

删除播放源

按 UUID 删除播放源。

播放源 UUID *

路径参数：播放源 UUID

POST /api/music/xiaoying/import 累计调用 0 次

批量导入

上传 JSON 文件批量导入音乐+播放源（单文件 ≤10MB、单次 ≤9999 条，不去重）。

JSON 文件 *

multipart 文件字段 file，内容为 JSON 数组。页面在线调试暂不支持文件上传，请在代码中调用。

示例单条：{"name":"晴天","singer":["周杰伦"],"online":true,"music_sources":["https://..."]}
部分成功：单条记录失败只回滚该条；同名且同歌手的重复记录（与库中已有或同文件内前面已接受者比较，忽略顺序/大小写）计入 failures，其余正常入库。

GET /api/music/xiaoying/export 累计调用 0 次

批量导出

导出全部音乐（与导入格式一致，可直接回灌导入）：≤9999 条返回单个 .json；超出返回 .zip（内含多个 ≤9999 条的 json）。

关键词

选填：匹配音乐名称/歌手

在线状态

选填：不传导出全部（含离线）

返回为文件下载（Content-Disposition: attachment），不走统一 JSON 包裹，curl 需加 -OJ 或 -o 保存文件。
导出内容与「批量导入」的 JSON 数组格式完全一致（name / singer / online / music_sources），可直接回灌导入。
≤9999 条返回单个 .json；超出返回 .zip，内含 xiaoying_music_1.json、xiaoying_music_2.json…每个文件 ≤9999 条。
文档页在线调试面板对二进制 zip 只能显示乱码文本，建议用 curl / 代码下载。