Mymusic3/api.md

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):

  {
    "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):

  {
    "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):

  {
    "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.

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).