音樂服務

音樂聚合能力：愛聽音樂網抓取（首頁/歌手/歌曲/搜索）與小影音樂自有曲庫的增刪改查。當前接入 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 累計調用 0 次

首頁數據

返回熱門歌手、歌曲飆升榜、流行趨勢榜三個模塊。

響應說明外層統一格式

字段	類型	說明
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 累計調用 0 次

歌手詳情

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

歌手頁 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 累計調用 0 次

歌曲詳情

歌曲基本信息 + 播放鏈接 + 歌詞 + 每日推薦。

歌曲頁 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 累計調用 0 次

搜索音樂

按關鍵詞搜索歌曲（分頁）。

關鍵詞 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 累計調用 0 次

音樂列表查詢

按關鍵詞/在線狀態查詢音樂（分頁）；不傳 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 累計調用 0 次

創建音樂

新建一條音樂，返回 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> 累計調用 0 次

獲取音樂詳情

按音樂 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> 累計調用 0 次

更新音樂

部分字段更新音樂（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> 累計調用 0 次

刪除音樂

按 UUID 刪除音樂（其播放源級聯刪除）。

音樂 UUID music_id *

路徑參數：要刪除的音樂 UUID

響應說明外層統一格式

刪除成功時 data 為 null（無返回數據）。

POST /api/music/xiaoying/music_sources 累計調用 0 次

創建播放源

給某首音樂新增一個播放鏈接。

音樂 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 累計調用 0 次

批量導入

上傳 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 累計調用 0 次

批量導出

導出全部音樂（與導入格式一致，可直接回灌導入）：≤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 分片。