API 接口文档

完整的 API 接口参考文档。

通用说明

基础 URL

https://api.ygking.top

请替换为你自己的部署地址。

响应格式

所有 API 返回 JSON 格式，基础结构如下：

json

{
  "code": 0,        // 0 表示成功，其他为错误码
  "data": {...},    // 返回数据
  "message": "..."  // 错误信息（仅在出错时）
}

CORS 支持

所有 API 支持跨域请求：

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type

搜索 API

GET /api/search

搜索歌曲、歌手、专辑或歌单。

请求参数

参数	类型	必填	默认值	说明
`keyword`	string	✅	-	搜索关键词
`type`	string	-	`song`	搜索类型
`num`	int	-	`20`	返回数量 (1-60)
`page`	int	-	`1`	页码

type 可选值

值	说明
`song`	搜索歌曲
`singer`	搜索歌手
`album`	搜索专辑
`playlist`	搜索歌单

请求示例

bash

GET /api/search?keyword=周杰伦&type=song&num=10&page=1

响应示例

json

{
  "code": 0,
  "data": {
    "list": [
      {
        "mid": "0039MnYb0qxYhV",
        "id": 97773,
        "title": "晴天",
        "singer": [
          {
            "mid": "0025NhlN2yWrP4",
            "name": "周杰伦"
          }
        ],
        "album": {
          "mid": "002fRO0N4FftzY",
          "name": "叶惠美"
        },
        "interval": 269,
        "pay": {
          "pay_play": 1
        }
      }
    ],
    "total": 1000
  }
}

歌曲 API

GET /api/song/url

获取歌曲播放链接。支持批量获取，自动降级音质。

请求参数

参数	类型	必填	默认值	说明
`mid`	string	✅	-	歌曲 MID，多个用逗号分隔
`quality`	string	-	`flac`	音质

quality 可选值

值	说明	格式
`master`	臻品母带 24Bit 192kHz	FLAC
`atmos` / `atmos_2`	臻品全景声 16Bit 44.1kHz	FLAC
`atmos_51`	臻品音质 16Bit 44.1kHz	FLAC
`flac`	无损音质	FLAC
`320`	高品质	MP3 320kbps
`128`	标准音质	MP3 128kbps

如果请求的音质不可用，会自动按上表从上到下降级。

请求示例

bash

# 单首歌曲
GET /api/song/url?mid=0039MnYb0qxYhV&quality=320

# 多首歌曲
GET /api/song/url?mid=0039MnYb0qxYhV,004Z8Ihr0JIu5s&quality=flac

响应示例

json

{
  "code": 0,
  "data": {
    "0039MnYb0qxYhV": "https://isure.stream.qqmusic.qq.com/..."
  }
}

GET /api/song/detail

获取歌曲详细信息。

请求参数

参数	类型	必填	说明
`mid`	string	✅*	歌曲 MID
`id`	int	✅*	歌曲 ID

*mid 和 id 二选一，优先使用 mid

请求示例

bash

GET /api/song/detail?mid=0039MnYb0qxYhV

响应示例

json

{
  "code": 0,
  "data": {
    "mid": "0039MnYb0qxYhV",
    "id": 97773,
    "title": "晴天",
    "singer": [
      { "mid": "0025NhlN2yWrP4", "name": "周杰伦" }
    ],
    "album": {
      "mid": "002fRO0N4FftzY",
      "name": "叶惠美"
    },
    "interval": 269,
    "genre": 1,
    "language": 0,
    "publish_date": "2003-07-31"
  }
}

GET /api/song/cover

获取歌曲封面图片。返回 302 重定向到实际图片 URL。

请求参数

参数	类型	必填	默认值	说明
`mid`	string	✅*	-	歌曲 MID（自动获取专辑信息）
`album_mid`	string	✅*	-	专辑 MID（直接获取封面）
`size`	int	-	`300`	图片尺寸
`validate`	bool	-	`true`	是否验证图片可用性

*mid 和 album_mid 二选一

size 可选值

值	说明
`150`	小图 (150×150)
`300`	中图 (300×300, 默认)
`500`	大图 (500×500)
`800`	超大图 (800×800)

请求示例

bash

# 通过歌曲 MID
GET /api/song/cover?mid=0039MnYb0qxYhV&size=300

# 通过专辑 MID
GET /api/song/cover?album_mid=002fRO0N4FftzY&size=500

响应说明

成功：返回 HTTP 302 重定向到图片 URL
可直接用于 <img> 标签的 src 属性

歌词 API

GET /api/lyric

获取歌词，自动解密 LRC/QRC 格式。

请求参数

参数	类型	必填	默认值	说明
`mid`	string	✅*	-	歌曲 MID
`id`	int	✅*	-	歌曲 ID
`qrc`	bool	-	`false`	是否获取逐字歌词 (QRC XML 格式)
`trans`	bool	-	`false`	是否获取翻译歌词
`roma`	bool	-	`false`	是否获取罗马音歌词 (XML 格式)

*mid 和 id 二选一

请求示例

bash

# 基础歌词
GET /api/lyric?mid=0039MnYb0qxYhV

# 逐字歌词 + 翻译 + 罗马音
GET /api/lyric?mid=0039MnYb0qxYhV&qrc=1&trans=1&roma=1

响应示例

json

{
  "code": 0,
  "data": {
    "lyric": "[00:00.00]晴天 - 周杰伦\n[00:01.00]词：周杰伦\n...",
    "trans": "[00:00.00]Sunny Day\n...",
    "roma": "<QrcInfos>...</QrcInfos>"
  }
}

返回字段说明

字段	说明
`lyric`	歌词（LRC 格式，开启 `qrc` 时为 QRC XML）
`trans`	翻译歌词（需传 `trans=1`）
`roma`	罗马音歌词（需传 `roma=1`，XML 格式）

专辑 API

GET /api/album

获取专辑详情及歌曲列表。

请求参数

参数	类型	必填	说明
`mid`	string	✅	专辑 MID

请求示例

bash

GET /api/album?mid=002fRO0N4FftzY

响应示例

json

{
  "code": 0,
  "data": {
    "mid": "002fRO0N4FftzY",
    "name": "叶惠美",
    "singer": {
      "mid": "0025NhlN2yWrP4",
      "name": "周杰伦"
    },
    "publish_date": "2003-07-31",
    "song_count": 11,
    "songs": [
      {
        "mid": "...",
        "title": "...",
        "singer": [...]
      }
    ]
  }
}

歌单 API

GET /api/playlist

获取歌单详情及歌曲列表。

请求参数

参数	类型	必填	说明
`id`	int	✅	歌单 ID

请求示例

bash

GET /api/playlist?id=8052190267

响应示例

json

{
  "code": 0,
  "data": {
    "id": 8052190267,
    "name": "周杰伦精选",
    "creator": {
      "name": "...",
      "id": 0
    },
    "song_count": 50,
    "songs": [
      {
        "mid": "...",
        "title": "...",
        "singer": [...]
      }
    ]
  }
}

歌手 API

GET /api/singer

获取歌手信息及热门歌曲。

请求参数

参数	类型	必填	说明
`mid`	string	✅	歌手 MID

请求示例

bash

GET /api/singer?mid=0025NhlN2yWrP4

响应示例

json

{
  "code": 0,
  "data": {
    "mid": "0025NhlN2yWrP4",
    "name": "周杰伦",
    "fans": 10000000,
    "songs": [
      {
        "mid": "...",
        "title": "...",
        "singer": [...]
      }
    ]
  }
}

排行榜 API

GET /api/top

获取排行榜列表或指定排行榜歌曲。

请求参数

参数	类型	必填	默认值	说明
`id`	int	-	-	排行榜 ID，不传则返回榜单列表
`num`	int	-	`100`	返回歌曲数量

常用排行榜 ID

ID	名称
4	巅峰榜·流行指数
26	巅峰榜·热歌
27	巅峰榜·新歌
62	巅峰榜·网络歌曲

请求示例

bash

# 获取排行榜列表
GET /api/top

# 获取指定排行榜
GET /api/top?id=4&num=50

错误码

错误码	说明
0	成功
400	参数错误
401	凭证无效
404	资源不存在
500	服务器错误

API 接口文档 ​

通用说明 ​

基础 URL ​

响应格式 ​

CORS 支持 ​

搜索 API ​

GET /api/search ​

请求参数 ​

type 可选值 ​

请求示例 ​

响应示例 ​

歌曲 API ​

GET /api/song/url ​

请求参数 ​

quality 可选值 ​

请求示例 ​

响应示例 ​

GET /api/song/detail ​

请求参数 ​

请求示例 ​

响应示例 ​

GET /api/song/cover ​

请求参数 ​

size 可选值 ​

请求示例 ​

响应说明 ​

歌词 API ​

GET /api/lyric ​

请求参数 ​

请求示例 ​

响应示例 ​

返回字段说明 ​

专辑 API ​

GET /api/album ​

请求参数 ​

请求示例 ​

响应示例 ​

歌单 API ​

GET /api/playlist ​

请求参数 ​

请求示例 ​

响应示例 ​

歌手 API ​

GET /api/singer ​

请求参数 ​

请求示例 ​

响应示例 ​

排行榜 API ​

GET /api/top ​

请求参数 ​

常用排行榜 ID ​

请求示例 ​

错误码 ​

API 接口文档

通用说明

基础 URL

响应格式

CORS 支持

搜索 API

GET /api/search

请求参数

type 可选值

请求示例

响应示例

歌曲 API

GET /api/song/url

请求参数

quality 可选值

请求示例

响应示例

GET /api/song/detail

请求参数

请求示例

响应示例

GET /api/song/cover

请求参数

size 可选值

请求示例

响应说明

歌词 API

GET /api/lyric

请求参数

请求示例

响应示例

返回字段说明

专辑 API

GET /api/album

请求参数

请求示例

响应示例

歌单 API

GET /api/playlist

请求参数

请求示例

响应示例

歌手 API

GET /api/singer

请求参数

请求示例

响应示例

排行榜 API

GET /api/top

请求参数

常用排行榜 ID

请求示例

错误码