音乐服务

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

/api/music/

服务说明

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

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

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

响应格式

所有接口返回同一个 JSON 信封，业务数据都在 data 里：

{
  "code": 10000,
  "msg": "成功",
  "data": { ... }
}

code：业务状态码，10000 表示成功；其余为各类错误，完整清单见「错误码」页。
msg：给人看的提示文案，可直接展示给终端用户，但不要用它做逻辑判断。
data：业务数据；出错时通常为 null。各接口 data 的具体字段见该接口的「响应说明」。

判断成功与否请看 code，不要依赖 HTTP 状态码。查看完整错误码

爱听音乐网 2t58

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

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

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

首页数据

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

响应说明外层统一格式

字段	类型	说明
hot_singers	array	热门歌手列表
hot_singers[].name	string	歌手名
hot_singers[].image	string	头像图片地址
hot_singers[].singer_url	string	歌手页地址
rising_chart	array	歌曲飙升榜
rising_chart[].song_name	string	歌曲名
rising_chart[].artists	array	歌手名列表
rising_chart[].song_url	string	歌曲页地址
trend_chart	array	流行趋势榜
trend_chart[].song_name	string	歌曲名
trend_chart[].artists	array	歌手名列表
trend_chart[].song_url	string	歌曲页地址

返回示例

{
  "hot_singers": [
    {"name": "示例歌手", "image": "https://img.2t58.com/xxx.jpg",
     "singer_url": "https://www.2t58.com/singer/bm1z/1.html"}
  ],
  "rising_chart": [
    {"song_name": "示例歌曲", "artists": ["示例歌手"],
     "song_url": "https://www.2t58.com/song/d3dkc2t3.html"}
  ],
  "trend_chart": [
    {"song_name": "示例歌曲", "artists": ["示例歌手"],
     "song_url": "https://www.2t58.com/song/d3dkc2t3.html"}
  ]
}

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

歌手详情

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

歌手页 URL url *

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

响应说明外层统一格式

字段	类型	说明
singer	object	歌手基本信息
singer.name	string	歌手名称
singer.cover	string	封面图地址
singer.intro	string	歌手简介
songs	array	歌曲列表
songs[].song_name	string	歌曲名
songs[].artists	array	歌手名列表
songs[].song_url	string	歌曲页地址
pagination	object	分页信息；无分页时为 null
pagination.current	object	当前页 {page,url}
pagination.current.page	int	页码
pagination.current.url	string	页面地址
pagination.first	object	首页 {page,url}；不存在为 null
pagination.prev	object	上一页 {page,url}；不存在为 null
pagination.next	object	下一页 {page,url}；不存在为 null
pagination.last	object	尾页 {page,url}；不存在为 null

返回示例

{
  "singer": {"name": "示例歌手", "cover": "https://img.2t58.com/xxx.jpg",
             "intro": "歌手简介"},
  "songs": [
    {"song_name": "示例歌曲", "artists": ["示例歌手"],
     "song_url": "https://www.2t58.com/song/d3dkc2t3.html"}
  ],
  "pagination": {
    "current": {"page": 1, "url": "https://www.2t58.com/singer/bm1z/1.html"},
    "first": null,
    "prev": null,
    "next": {"page": 2, "url": "https://www.2t58.com/singer/bm1z/2.html"},
    "last": {"page": 5, "url": "https://www.2t58.com/singer/bm1z/5.html"}
  }
}

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

歌曲详情

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

歌曲页 URL url *

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

响应说明外层统一格式

字段	类型	说明
song	object	歌曲基本信息
song.song_name	string	歌曲名
song.artists	array	歌手名列表
song.cover	string	封面图地址
play_url	string	播放直链（解密后）；失败为空字符串
lyrics	string	LRC 格式歌词；失败为空字符串
daily_recommend	array	随机推荐列表
daily_recommend[].song_name	string	歌曲名
daily_recommend[].artists	array	歌手名列表
daily_recommend[].song_url	string	歌曲页地址

返回示例

{
  "song": {"song_name": "示例歌曲", "artists": ["示例歌手"],
           "cover": "https://img.2t58.com/xxx.jpg"},
  "play_url": "https://music.2t58.com/xxx.mp3",
  "lyrics": "示例歌词",
  "daily_recommend": [
    {"song_name": "示例歌曲", "artists": ["示例歌手"],
     "song_url": "https://www.2t58.com/song/d3dkc2t3.html"}
  ]
}

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

搜索音乐

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

关键词 keyword *

搜索关键词（必填）

页码 page

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

响应说明外层统一格式

字段	类型	说明
songs	array	搜索结果歌曲列表
songs[].song_name	string	歌曲名
songs[].artists	array	歌手名列表
songs[].song_url	string	歌曲页地址
pagination	object	分页信息；无分页时为 null
pagination.current	object	当前页 {page,url}
pagination.current.page	int	页码
pagination.current.url	string	页面地址
pagination.first	object	首页 {page,url}；不存在为 null
pagination.prev	object	上一页 {page,url}；不存在为 null
pagination.next	object	下一页 {page,url}；不存在为 null
pagination.last	object	尾页 {page,url}；不存在为 null
total	int	搜索结果总条数

返回示例

{
  "songs": [
    {"song_name": "示例歌曲", "artists": ["示例歌手"],
     "song_url": "https://www.2t58.com/song/d3dkc2t3.html"}
  ],
  "pagination": {
    "current": {"page": 1, "url": "https://www.2t58.com/so/%E7%8E%8B%E5%B0%8F%E8%8D%89/1.html"},
    "first": null,
    "prev": null,
    "next": {"page": 2, "url": "https://www.2t58.com/so/%E7%8E%8B%E5%B0%8F%E8%8D%89/2.html"},
    "last": {"page": 3, "url": "https://www.2t58.com/so/%E7%8E%8B%E5%B0%8F%E8%8D%89/3.html"}
  },
  "total": 30
}

小影音乐

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

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

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

音乐列表查询

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

关键词 keyword

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

在线状态 online

选填：true/false

页码 page

选填：默认 1

每页条数 page_size

选填：1-100，默认 10

响应说明外层统一格式

字段	类型	说明
items	array	音乐列表
items[].id	string	音乐 UUID
items[].name	string	音乐名称
items[].singer	array	歌手列表
items[].online	bool	是否在线
items[].create_time	string	创建时间
items[].updated_time	string	更新时间
total	int	总条数
page	int	当前页码
page_size	int	每页条数
total_pages	int	总页数

返回示例

{
  "items": [
    {"id": "5f8e0b2c-1a3d-4e5f-8a9b-0c1d2e3f4a5b", "name": "示例歌曲",
     "singer": ["示例歌手"], "online": true,
     "create_time": "2026-10-01 12:00:00", "updated_time": "2026-10-01 12:00:00"}
  ],
  "total": 1,
  "page": 1,
  "page_size": 10,
  "total_pages": 1
}

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

创建音乐

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

音乐名称 name *

音乐名称（必填）

歌手 singer *

歌手（必填，至少一位）

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

在线状态 online

选填：默认 true

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

响应说明外层统一格式

字段	类型	说明
id	string	音乐 UUID（即 music_id）
name	string	音乐名称
singer	array	歌手列表
online	bool	是否在线
create_time	string	创建时间
updated_time	string	更新时间

返回示例

{
  "id": "5f8e0b2c-1a3d-4e5f-8a9b-0c1d2e3f4a5b",
  "name": "示例歌曲",
  "singer": ["示例歌手"],
  "online": true,
  "create_time": "2026-10-01 12:00:00",
  "updated_time": "2026-10-01 12:00:00"
}

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

获取音乐详情

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

音乐 UUID music_id *

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

响应说明外层统一格式

字段	类型	说明
id	string	音乐 UUID
name	string	音乐名称
singer	array	歌手列表
online	bool	是否在线
create_time	string	创建时间
updated_time	string	更新时间
music_sources	array	该音乐的播放源列表
music_sources[].id	string	播放源 UUID
music_sources[].music_id	string	所属音乐 UUID
music_sources[].url	string	播放链接
music_sources[].create_time	string	创建时间
music_sources[].updated_time	string	更新时间

返回示例

{
  "id": "5f8e0b2c-1a3d-4e5f-8a9b-0c1d2e3f4a5b",
  "name": "示例歌曲",
  "singer": ["示例歌手"],
  "online": true,
  "create_time": "2026-10-01 12:00:00",
  "updated_time": "2026-10-01 12:00:00",
  "music_sources": [
    {"id": "9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
     "music_id": "5f8e0b2c-1a3d-4e5f-8a9b-0c1d2e3f4a5b",
     "url": "https://music.example.com/xxx.mp3",
     "create_time": "2026-10-01 12:00:00", "updated_time": "2026-10-01 12:00:00"}
  ]
}

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

更新音乐

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

音乐 UUID music_id *

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

音乐名称 name

选填：新名称

歌手 singer

选填：整体替换歌手列表

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

在线状态 online

选填：true/false

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

响应说明外层统一格式

字段	类型	说明
id	string	音乐 UUID
name	string	音乐名称
singer	array	歌手列表
online	bool	是否在线
create_time	string	创建时间
updated_time	string	更新时间

返回示例

{
  "id": "5f8e0b2c-1a3d-4e5f-8a9b-0c1d2e3f4a5b",
  "name": "示例歌曲",
  "singer": ["示例歌手"],
  "online": false,
  "create_time": "2026-10-01 12:00:00",
  "updated_time": "2026-10-02 09:30:00"
}

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

删除音乐

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

音乐 UUID music_id *

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

响应说明外层统一格式

删除成功时 data 为 null（无返回数据）。

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

创建播放源

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

音乐 UUID music_id *

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

播放链接 url *

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

响应说明外层统一格式

字段	类型	说明
id	string	播放源 UUID
music_id	string	所属音乐 UUID
url	string	播放链接
create_time	string	创建时间
updated_time	string	更新时间

返回示例

{
  "id": "9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "music_id": "5f8e0b2c-1a3d-4e5f-8a9b-0c1d2e3f4a5b",
  "url": "https://music.example.com/xxx.mp3",
  "create_time": "2026-10-01 12:00:00",
  "updated_time": "2026-10-01 12:00:00"
}

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

更新播放源

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

播放源 UUID source_id *

路径参数：播放源 UUID

播放链接 url

选填：新播放地址

响应说明外层统一格式

字段	类型	说明
id	string	播放源 UUID
music_id	string	所属音乐 UUID
url	string	播放链接
create_time	string	创建时间
updated_time	string	更新时间

返回示例

{
  "id": "9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "music_id": "5f8e0b2c-1a3d-4e5f-8a9b-0c1d2e3f4a5b",
  "url": "https://music.example.com/new.mp3",
  "create_time": "2026-10-01 12:00:00",
  "updated_time": "2026-10-02 09:30:00"
}

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

删除播放源

按 UUID 删除播放源。

播放源 UUID source_id *

路径参数：播放源 UUID

响应说明外层统一格式

删除成功时 data 为 null（无返回数据）。

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

批量导入

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

JSON 文件 file *

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

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

响应说明外层统一格式

字段	类型	说明
total	int	提交总条数
success_count	int	成功入库条数
failed_count	int	失败条数
failures	array	失败明细列表
failures[].index	int	记录在数组中的下标（从 0 起）
failures[].name	string	该记录的 name；取不到为空字符串
failures[].msg	string	失败原因

返回示例

{
  "total": 2,
  "success_count": 1,
  "failed_count": 1,
  "failures": [
    {"index": 1, "name": "示例歌曲", "msg": "资源已存在: 同名且同歌手的音乐已存在"}
  ]
}

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

批量导出

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

关键词 keyword

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

在线状态 online

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

返回为文件下载（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 / 代码下载。

响应说明外层统一格式

该接口返回文件下载（Content-Disposition: attachment），不走 {code,msg,data} 统一包裹：内容为与「批量导入」同格式的 JSON 数组，≤9999 条为单个 .json，超出为 .zip 分片。

音乐服务 API 常见问题

音乐 API 提供哪些能力？

两条线路：爱听音乐网抓取（首页 home、歌手 singer、歌曲 song、搜索 search），以及小影音乐自有曲库（增删改查、播放源管理、批量导入导出）。典型用法是「先用第三方曲库找歌，再把要长期用的沉淀到自己的库」。

能按歌名或歌手搜歌吗？

能，搜索端点传关键词返回歌曲列表，每条带歌曲 ID；再用歌曲详情取完整信息与播放地址。

自建曲库怎么批量导入？

用批量导入端点（/api/music/xiaoying/import）一次性写入多条，导出端点可把现有数据导成结构化文本，便于迁移与备份。

播放地址能直接给前端用吗？

歌曲详情返回上游给的播放地址，是否带时效、能否跨域以上游为准；前端播放前建议判断地址可用性，失败时重新取详情，不要长期缓存直链。

音乐服务接口怎么接入？需要签名吗？

音乐服务挂在 /api/music/ 前缀下：需签名的端点按 app_id + timestamp + nonce + sign（HMAC-SHA256，密钥为 APPSECRET）调用，开放端点直接请求即可。拿不准时用本页右侧的「在线调试」—— 它会代签并把你实际发出的请求与真实响应都回显出来。

音乐服务的返回结构和错误码怎么看？

全部接口统一返回 {code, msg, data}：code=10000 表示成功，2xxxx 为业务错误，3xxxx / 4xxxx / 5xxxx 分别为外部依赖、客户端与系统错误。完整含义与处理建议见「错误码总表」（/docs/errors/）。