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

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