音樂服務

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