mirror of
https://github.com/timeshiftsauce/CeruMusic.git
synced 2025-11-25 11:29:42 +08:00
198 lines
4.2 KiB
Markdown
198 lines
4.2 KiB
Markdown
# 音乐API接口文档
|
||
|
||
## 概述
|
||
|
||
这是一个基于 Meting 库的音乐API接口，支持多个音乐平台的数据获取，包括歌曲信息、专辑、歌词、播放链接等。
|
||
|
||
## 基础信息
|
||
|
||
- **请求方式**: GET
|
||
- **返回格式**: JSON
|
||
- **字符编码**: UTF-8
|
||
- **跨域支持**: 是
|
||
|
||
## 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||
| ------ | ------ | ---- | ------- | -------------- |
|
||
| server | string | 否 | netease | 音乐平台 |
|
||
| type | string | 否 | search | 请求类型 |
|
||
| id | string | 否 | hello | 查询ID或关键词 |
|
||
|
||
### 支持的音乐平台 (server)
|
||
|
||
| 平台代码 | 平台名称 |
|
||
| -------- | ---------- |
|
||
| netease | 网易云音乐 |
|
||
| tencent | QQ音乐 |
|
||
| baidu | 百度音乐 |
|
||
| xiami | 虾米音乐 |
|
||
| kugou | 酷狗音乐 |
|
||
| kuwo | 酷我音乐 |
|
||
|
||
### 支持的请求类型 (type)
|
||
|
||
| 类型 | 说明 | id参数说明 |
|
||
| -------- | ------------ | ---------------- |
|
||
| search | 搜索歌曲 | 搜索关键词 |
|
||
| song | 获取歌曲详情 | 歌曲ID |
|
||
| album | 获取专辑信息 | 专辑ID |
|
||
| artist | 获取歌手信息 | 歌手ID |
|
||
| playlist | 获取歌单信息 | 歌单ID |
|
||
| lrc | 获取歌词 | 歌曲ID |
|
||
| url | 获取播放链接 | 歌曲ID |
|
||
| pic | 获取封面图片 | 歌曲/专辑/歌手ID |
|
||
|
||
## 响应格式
|
||
|
||
### 成功响应
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": {
|
||
// 具体数据内容，根据请求类型不同而不同
|
||
}
|
||
}
|
||
```
|
||
|
||
### 错误响应
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "错误信息"
|
||
}
|
||
```
|
||
|
||
## 请求示例
|
||
|
||
### 1. 搜索歌曲
|
||
|
||
```
|
||
GET /?server=netease&type=search&id=周杰伦
|
||
```
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": [
|
||
{
|
||
"id": "186016",
|
||
"name": "青花瓷",
|
||
"artist": ["周杰伦"],
|
||
"album": "我很忙",
|
||
"pic_id": "109951163240682406",
|
||
"url_id": "186016",
|
||
"lyric_id": "186016"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 2. 获取歌曲详情
|
||
|
||
```
|
||
GET /?server=netease&type=song&id=186016
|
||
```
|
||
|
||
### 3. 获取歌词
|
||
|
||
```
|
||
GET /?server=netease&type=lrc&id=186016
|
||
```
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": {
|
||
"lyric": "[00:00.00] 作词 : 方文山\n[00:01.00] 作曲 : 周杰伦\n[00:22.78]素胚勾勒出青花笔锋浓转淡\n..."
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 获取播放链接
|
||
|
||
```
|
||
GET /?server=netease&type=url&id=186016
|
||
```
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": [
|
||
{
|
||
"id": "186016",
|
||
"url": "http://music.163.com/song/media/outer/url?id=186016.mp3",
|
||
"size": 4729252,
|
||
"br": 128
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 5. 获取专辑信息
|
||
|
||
```
|
||
GET /?server=netease&type=album&id=18905
|
||
```
|
||
|
||
### 6. 获取歌手信息
|
||
|
||
```
|
||
GET /?server=netease&type=artist&id=6452
|
||
```
|
||
|
||
### 7. 获取歌单信息
|
||
|
||
```
|
||
GET /?server=netease&type=playlist&id=19723756
|
||
```
|
||
|
||
### 8. 获取封面图片
|
||
|
||
```
|
||
GET /?server=netease&type=pic&id=186016
|
||
```
|
||
|
||
## 错误码说明
|
||
|
||
| 错误信息 | 说明 |
|
||
| ------------------- | ---------------- |
|
||
| require id. | 缺少必需的id参数 |
|
||
| unsupported server. | 不支持的音乐平台 |
|
||
| unsupported type. | 不支持的请求类型 |
|
||
|
||
## 注意事项
|
||
|
||
1. **代理支持**: 如果设置了环境变量 `METING_PROXY`，API会使用代理访问音乐平台
|
||
2. **Cookie支持**: API会自动传递请求中的Cookie到音乐平台
|
||
3. **跨域访问**: API已配置CORS，支持跨域请求
|
||
4. **请求频率**: 建议控制请求频率，避免被音乐平台限制
|
||
5. **数据时效性**: 音乐平台的数据可能会发生变化，建议适当缓存但不要过度依赖
|
||
|
||
## 使用建议
|
||
|
||
1. **错误处理**: 请务必检查响应中的 `success` 字段
|
||
2. **数据验证**: 返回的数据结构可能因平台而异，请做好数据验证
|
||
3. **备用方案**: 建议支持多个音乐平台作为备用数据源
|
||
4. **缓存策略**: 对于不经常变化的数据（如歌词、专辑信息）建议进行缓存
|
||
|
||
## 技术实现
|
||
|
||
本API基于以下技术栈：
|
||
|
||
- **PHP**: 后端语言
|
||
- **Meting**: 音乐数据获取库
|
||
- **Composer**: 依赖管理
|
||
|
||
## 更新日志
|
||
|
||
- **v1.0.0**: 初始版本，支持基础的音乐数据获取功能
|