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