shiyue/Mymusic3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
50f7869a05fcb89f6b594454320f6ee3e6e21e62
Mymusic3/api.md
史悦 50f7869a05 feat: 实现网易云音乐同步服务核心功能与UI改进 
添加完整的网易云音乐同步到Navidrome的功能实现，包括：
1. 新增Docker支持与相关配置文件
2. 实现歌单同步逻辑与Navidrome API集成
3. 改进前端UI界面与交互体验
4. 添加状态监控与错误处理机制
5. 实现定时同步功能与进度显示
2026-01-12 20:03:30 +08:00

444 lines
14 KiB
Markdown
Raw Blame History

# TuneHub API 文档
TuneHub 是一个统一的音乐信息解析服务。它打破了不同音乐平台之间的壁垒，提供了一套标准化的 API 接口。
**Base URL:** `https://music-dl.sayqz.com`
**Version:** 1.0.0
---
## 核心 API
### 1. 获取歌曲基本信息
获取歌曲的名称、歌手、专辑等基本元数据信息。
* **Method:** `GET`
* **Endpoint:** `/api/`
* **Query Parameters:**
* `source`: `string` - **必需**. 平台标识 (例如: `netease`, `kuwo`, `qq`).
* `id`: `string` - **必需**. 歌曲 ID.
* `type`: `string` - **必需**. 固定为 `info`.
* **Response Example (200 OK):**
```json
{
"code": 200,
"message": "success",
"data": {
"name": "歌曲名称",
"artist": "歌手名称",
"album": "专辑名称",
"url": "https://music-dl.sayqz.com/api/?source=netease&id=123456&type=url",
"pic": "https://music-dl.sayqz.com/api/?source=netease&id=123456&type=pic",
"lrc": "https://music-dl.sayqz.com/api/?source=netease&id=123456&type=lrc"
},
"timestamp": "2025-11-23T12:00:00.000+08:00"
}
```
### 2. 获取音乐文件链接
获取音乐文件链接。成功时返回 302 Redirect 到实际的音乐文件 URL。
* **Method:** `GET`
* **Endpoint:** `/api/`
* **Query Parameters:**
* `source`: `string` - **必需**. 平台标识.
* `id`: `string` - **必需**. 歌曲 ID.
* `type`: `string` - **必需**. 固定为 `url`.
* `br`: `string` - *可选*. 音质 (默认: `320k`). 可选值: `128k`, `320k`, `flac`, `flac24bit`.
### 3. 获取专辑封面
获取歌曲的专辑封面图片。成功时返回 302 Redirect 到图片 URL。
* **Method:** `GET`
* **Endpoint:** `/api/`
* **Query Parameters:**
* `source`: `string` - **必需**. 平台标识.
* `id`: `string` - **必需**. 歌曲 ID.
* `type`: `string` - **必需**. 固定为 `pic`.
### 4. 获取歌词
获取LRC格式的歌词。
* **Method:** `GET`
* **Endpoint:** `/api/`
* **Query Parameters:**
* `source`: `string` - **必需**. 平台标识.
* `id`: `string` - **必需**. 歌曲 ID.
* `type`: `string` - **必需**. 固定为 `lrc`.
* **Response Example (200 OK, text/plain):**
```
[00:00.00]歌词第一行
[00:05.50]歌词第二行
```
### 5. 搜索歌曲
* **Method:** `GET`
* **Endpoint:** `/api/`
* **Query Parameters:**
* `source`: `string` - **必需**. 平台标识.
* `type`: `string` - **必需**. 固定为 `search`.
* `keyword`: `string` - **必需**. 搜索关键词.
* `limit`: `integer` - *可选*. 返回数量 (默认: 20).
* **Response Example (200 OK):**
```json
{
"code": 200,
"message": "success",
"data": {
"keyword": "周杰伦",
"total": 10,
"results": [
{
"id": "123456",
"name": "歌曲名称",
"artist": "周杰伦",
"album": "专辑名称",
"url": "https://music-dl.sayqz.com/api/?...",
"platform": "netease"
}
]
}
}
```
### 6. 聚合搜索
一次性并发请求所有启用的平台，并对结果进行智能混合排列。
* **Method:** `GET`
* **Endpoint:** `/api/`
* **Query Parameters:**
* `type`: `string` - **必需**. 固定为 `aggregateSearch`.
* `keyword`: `string` - **必需**. 搜索关键词.
* **Response Example (200 OK):**
```json
{
"code": 200,
"message": "success",
"data": {
"keyword": "周杰伦",
"results": [
{
"id": "123456",
"name": "歌曲名称",
"artist": "周杰伦",
"platform": "netease"
},
{
"id": "789012",
"name": "另一首歌",
"artist": "周杰伦",
"platform": "kuwo"
}
]
}
}
```
### 7. 获取歌单详情
* **Method:** `GET`
* **Endpoint:** `/api/`
* **Query Parameters:**
* `source`: `string` - **必需**. 平台标识.
* `id`: `string` - **必需**. 歌单 ID.
* `type`: `string` - **必需**. 固定为 `playlist`.
结果示例：
{
"code": 200,
"message": "success",
"data": {
"list": [
{
"id": "2722391361",
"name": "天后 (live)",
"artist": "李佳薇",
"album": "歌手2025 第8期",
"info": "https://music-dl.sayqz.com/api/?source=netease&id=2722391361&type=info",
"url": "https://music-dl.sayqz.com/api/?source=netease&id=2722391361&type=url",
"pic": "https://music-dl.sayqz.com/api/?source=netease&id=2722391361&type=pic",
"lrc": "https://music-dl.sayqz.com/api/?source=netease&id=2722391361&type=lrc",
"types": [
"flac24bit",
"flac",
"320k",
"128k"
]
},
{
"id": "1368753797",
"name": "法兰西多士",
"artist": "告五人",
"album": "我肯定在几百年前就说过爱你",
"info": "https://music-dl.sayqz.com/api/?source=netease&id=1368753797&type=info",
"url": "https://music-dl.sayqz.com/api/?source=netease&id=1368753797&type=url",
"pic": "https://music-dl.sayqz.com/api/?source=netease&id=1368753797&type=pic",
"lrc": "https://music-dl.sayqz.com/api/?source=netease&id=1368753797&type=lrc",
"types": [
"flac24bit",
"flac",
"320k",
"128k"
]
},
{
"id": "155886",
"name": "光明",
"artist": "汪峰",
"album": "信仰在空中飘扬",
"info": "https://music-dl.sayqz.com/api/?source=netease&id=155886&type=info",
"url": "https://music-dl.sayqz.com/api/?source=netease&id=155886&type=url",
"pic": "https://music-dl.sayqz.com/api/?source=netease&id=155886&type=pic",
"lrc": "https://music-dl.sayqz.com/api/?source=netease&id=155886&type=lrc",
"types": [
"flac",
"320k",
"128k"
]
},
{
"id": "569214247",
"name": "平凡的一天",
"artist": "毛不易",
"album": "平凡的一天",
"info": "https://music-dl.sayqz.com/api/?source=netease&id=569214247&type=info",
"url": "https://music-dl.sayqz.com/api/?source=netease&id=569214247&type=url",
"pic": "https://music-dl.sayqz.com/api/?source=netease&id=569214247&type=pic",
"lrc": "https://music-dl.sayqz.com/api/?source=netease&id=569214247&type=lrc",
"types": [
"flac",
"320k",
"128k"
]
},
{
"id": "1810392410",
"name": "回音",
"artist": "神秘的小鸡蛋",
"album": "感觉",
"info": "https://music-dl.sayqz.com/api/?source=netease&id=1810392410&type=info",
"url": "https://music-dl.sayqz.com/api/?source=netease&id=1810392410&type=url",
"pic": "https://music-dl.sayqz.com/api/?source=netease&id=1810392410&type=pic",
"lrc": "https://music-dl.sayqz.com/api/?source=netease&id=1810392410&type=lrc",
"types": [
"flac",
"320k",
"128k"
]
},
{
"id": "569200213",
"name": "消愁",
"artist": "毛不易",
"album": "平凡的一天",
"info": "https://music-dl.sayqz.com/api/?source=netease&id=569200213&type=info",
"url": "https://music-dl.sayqz.com/api/?source=netease&id=569200213&type=url",
"pic": "https://music-dl.sayqz.com/api/?source=netease&id=569200213&type=pic",
"lrc": "https://music-dl.sayqz.com/api/?source=netease&id=569200213&type=lrc",
"types": [
"flac",
"320k",
"128k"
]
},
{
"id": "2083191501",
"name": "郁郁而终",
"artist": "马英杰",
"album": "郁郁而终（重制版）",
"info": "https://music-dl.sayqz.com/api/?source=netease&id=2083191501&type=info",
"url": "https://music-dl.sayqz.com/api/?source=netease&id=2083191501&type=url",
"pic": "https://music-dl.sayqz.com/api/?source=netease&id=2083191501&type=pic",
"lrc": "https://music-dl.sayqz.com/api/?source=netease&id=2083191501&type=lrc",
"types": [
"flac24bit",
"flac",
"320k",
"128k"
]
},
{
"id": "1838919030",
"name": "王招君",
"artist": "任素汐",
"album": "TA·说",
"info": "https://music-dl.sayqz.com/api/?source=netease&id=1838919030&type=info",
"url": "https://music-dl.sayqz.com/api/?source=netease&id=1838919030&type=url",
"pic": "https://music-dl.sayqz.com/api/?source=netease&id=1838919030&type=pic",
"lrc": "https://music-dl.sayqz.com/api/?source=netease&id=1838919030&type=lrc",
"types": [
"flac24bit",
"flac",
"320k",
"128k"
]
},
{
"id": "2105734399",
"name": "风过千里",
"artist": "雪域任运",
"album": "风过千里",
"info": "https://music-dl.sayqz.com/api/?source=netease&id=2105734399&type=info",
"url": "https://music-dl.sayqz.com/api/?source=netease&id=2105734399&type=url",
"pic": "https://music-dl.sayqz.com/api/?source=netease&id=2105734399&type=pic",
"lrc": "https://music-dl.sayqz.com/api/?source=netease&id=2105734399&type=lrc",
"types": [
"flac",
"320k",
"128k"
]
},
{
"id": "1974443814",
"name": "我记得",
"artist": "赵雷",
"album": "署前街少年",
"info": "https://music-dl.sayqz.com/api/?source=netease&id=1974443814&type=info",
"url": "https://music-dl.sayqz.com/api/?source=netease&id=1974443814&type=url",
"pic": "https://music-dl.sayqz.com/api/?source=netease&id=1974443814&type=pic",
"lrc": "https://music-dl.sayqz.com/api/?source=netease&id=1974443814&type=lrc",
"types": [
"flac",
"320k",
"128k"
]
},
{
"id": "155899",
"name": "勇敢的心",
"artist": "汪峰",
"album": "勇敢的心",
"info": "https://music-dl.sayqz.com/api/?source=netease&id=155899&type=info",
"url": "https://music-dl.sayqz.com/api/?source=netease&id=155899&type=url",
"pic": "https://music-dl.sayqz.com/api/?source=netease&id=155899&type=pic",
"lrc": "https://music-dl.sayqz.com/api/?source=netease&id=155899&type=lrc",
"types": [
"flac",
"320k",
"128k"
]
},
{
"id": "1308081071",
"name": "作曲家 (Live)",
"artist": "刘郡格",
"album": "2018中国好声音 第8期",
"info": "https://music-dl.sayqz.com/api/?source=netease&id=1308081071&type=info",
"url": "https://music-dl.sayqz.com/api/?source=netease&id=1308081071&type=url",
"pic": "https://music-dl.sayqz.com/api/?source=netease&id=1308081071&type=pic",
"lrc": "https://music-dl.sayqz.com/api/?source=netease&id=1308081071&type=lrc",
"types": [
"flac",
"320k",
"128k"
]
},
{
"id": "488641876",
"name": "有一个地方叫远方",
"artist": "曾昭玮",
"album": "有一个地方叫远方",
"info": "https://music-dl.sayqz.com/api/?source=netease&id=488641876&type=info",
"url": "https://music-dl.sayqz.com/api/?source=netease&id=488641876&type=url",
"pic": "https://music-dl.sayqz.com/api/?source=netease&id=488641876&type=pic",
"lrc": "https://music-dl.sayqz.com/api/?source=netease&id=488641876&type=lrc",
"types": [
"flac",
"320k",
"128k"
]
}
],
"total": 13,
"source": "netease",
"info": {
"name": "为你降次元喜欢的音乐",
"pic": "https://p1.music.126.net/Qara552B1Q3VBJnwggJA2A==/109951171404861681.jpg",
"desc": "",
"author": "为你降次元",
"playCount": 1
}
},
"timestamp": "2026-01-12T18:32:10.516+08:00"
}
### 8. 获取排行榜列表
* **Method:** `GET`
* **Endpoint:** `/api/`
* **Query Parameters:**
* `source`: `string` - **必需**. 平台标识.
* `type`: `string` - **必需**. 固定为 `toplists`.
### 9. 获取排行榜歌曲
* **Method:** `GET`
* **Endpoint:** `/api/`
* **Query Parameters:**
* `source`: `string` - **必需**. 平台标识.
* `id`: `string` - **必需**. 排行榜 ID.
* `type`: `string` - **必需**. 固定为 `toplist`.
---
## 系统 API
### 10. 系统状态
* **Method:** `GET`
* **Endpoint:** `/status`
### 11. 健康检查
* **Method:** `GET`
* **Endpoint:** `/health`
---
## 统计 API
### 12. 获取统计数据
* **Method:** `GET`
* **Endpoint:** `/stats`
* **Query Parameters:**
* `period`: `string` - *可选*. 时间段 (默认: `today`).
* `groupBy`: `string` - *可选*. 分组依据 (默认: `platform`).
### 13. 获取统计摘要
* **Method:** `GET`
* **Endpoint:** `/stats/summary`
### 14. 平台统计概览
* **Method:** `GET`
* **Endpoint:** `/stats/platforms`
* **Query Parameters:**
* `period`: `string` - *可选*. 时间段 (默认: `today`).
### 15. QPS 统计
* **Method:** `GET`
* **Endpoint:** `/stats/qps`
* **Query Parameters:**
* `period`: `string` - *可选*. 时间段 (默认: `today`).
### 16. 趋势数据
* **Method:** `GET`
* **Endpoint:** `/stats/trends`
* **Query Parameters:**
* `period`: `string` - *可选*. 时间段 (默认: `week`).
### 17. 请求类型统计
* **Method:** `GET`
* **Endpoint:** `/stats/types`
* **Query Parameters:**
* `period`: `string` - *可选*. 时间段 (默认: `today`).
Reference in New Issue View Git Blame Copy Permalink