Music API 接口文档

目前支持：本地音乐扫描管理、歌曲搜索、流式播放、在线音乐解析（网易云/QQ音乐/酷狗）、歌单管理、收藏管理、播放历史记录
说明：本接口基于 Slim Framework 4 + MySQL 构建，支持本地音乐文件管理与多平台在线音乐解析聚合。仅用于个人学习和研究目的。

本地音乐 API

基础路径：/api/local

请求方法：GET / POST / DELETE

方法 路径 说明
扫描 & 管理
POST /api/local/scan 扫描本地音乐目录，自动读取文件元数据（标题、艺术家、专辑、时长、封面等）
GET /api/local/songs 获取本地歌曲列表（分页），支持排序和筛选
GET /api/local/songs/{id} 获取指定歌曲详情
GET /api/local/songs/{id}/play 流式播放音频（支持 HTTP Range 断点续传）
GET /api/local/songs/{id}/download 下载音乐文件
GET /api/local/songs/{id}/cover 获取歌曲封面图片
GET /api/local/search 搜索本地歌曲（按标题/艺术家/专辑）
GET /api/local/stats 本地音乐统计信息（总数、总时长、总大小等）
DELETE /api/local/songs/{id} 删除歌曲记录（仅删数据库记录，不删文件）

请求参数（歌曲列表）

参数名称 参数类型 是否必填 默认值 参数描述
page int 否 1 页码
page_size int 否 20 每页条数（最大100）
sort string 否 created_at 排序字段：title / artist / album / duration / file_size / played_count / created_at
order string 否 desc 排序方向：desc 降序 / asc 升序
artist string 否 无 按艺术家筛选
album string 否 无 按专辑筛选 
GET /api/local/songs?page=1&page_size=10&sort=title&order=asc

GET /api/local/search?keyword=周杰伦

POST /api/local/scan

在线音乐 API

基础路径：/api/online

请求方法：GET

方法 路径 说明
搜索 & 查询
GET /api/online/search 搜索歌曲（指定平台）
GET /api/online/search/all 多平台聚合搜索（同时搜索网易云/QQ/酷狗）
GET /api/online/platforms 获取已启用的平台列表
歌曲解析
GET /api/online/song/{platform}/{id} 获取歌曲详情
GET /api/online/song/{platform}/{id}/url 获取播放链接（VIP自动解锁，多音源解析）
GET /api/online/song/{platform}/{id}/download 下载歌曲（302重定向，VIP自动解锁）
GET /api/online/song/{platform}/{id}/lyric 获取歌词
GET /api/online/song/{platform}/{id}/cover 获取封面图片URL

请求参数（搜索）

参数名称 参数类型 是否必填 默认值 参数描述
keyword string 是 无 搜索关键词（歌曲名/歌手名）
platform string 否 netease 平台：netease / qq / kugou
page int 否 1 页码
limit int 否 20 每页数量（最大50） 
GET /api/online/search?keyword=周杰伦&platform=netease&page=1&limit=10

GET /api/online/search/all?keyword=晴天&limit=5

GET /api/online/song/netease/186016/url

GET /api/online/song/qq/001x5cvU2SEfX7/download

GET /api/online/song/qq/001x5cvU2SEfX7/lyric

GET /api/online/platforms

返回示例（搜索结果）

{
    "code": 0,
    "message": "success",
    "data": {
        "list": [
            {
                "id": "186016",
                "platform": "netease",
                "title": "晴天",
                "artist": "周杰伦",
                "album": "叶惠美",
                "duration": 269,
                "cover_url": "https://p2.music.126.net/..."
            }
        ],
        "total": 20,
        "page": 1
    }
}

在线试听 & 下载

VIP歌曲自动解锁，通过酷狗/咪咕/波点/酷我等多音源解析，搜索 → 播放 → 下载全流程支持

歌单管理 API

基础路径：/api/playlists

请求方法：GET / POST / PUT / DELETE

方法 路径 说明
歌单 CRUD
GET /api/playlists 歌单列表
POST /api/playlists 创建歌单
GET /api/playlists/{id} 歌单详情
PUT /api/playlists/{id} 更新歌单信息
DELETE /api/playlists/{id} 删除歌单
歌单内歌曲管理
GET /api/playlists/{id}/songs 歌单内歌曲列表
POST /api/playlists/{id}/songs 添加歌曲到歌单
POST /api/playlists/{id}/songs/batch 批量添加歌曲
DELETE /api/playlists/{id}/songs/{songId} 从歌单移除歌曲

创建歌单

POST /api/playlists
Content-Type: application/json

{
    "name": "我的歌单",
    "description": "描述文字",
    "cover_url": "https://example.com/cover.jpg",
    "is_public": true
}

添加歌曲到歌单（本地歌曲）

POST /api/playlists/1/songs
Content-Type: application/json

{
    "song_source": "local",
    "song_id": 5
}

添加歌曲到歌单（在线歌曲）

POST /api/playlists/1/songs
Content-Type: application/json

{
    "song_source": "online",
    "platform": "netease",
    "external_id": "186016",
    "title": "晴天",
    "artist": "周杰伦",
    "album": "叶惠美",
    "duration": 269
}

收藏 & 播放历史

收藏 API

基础路径：/api/favorites

方法 路径 说明
GET /api/favorites 收藏列表（分页）
POST /api/favorites 添加收藏
DELETE /api/favorites/{id} 取消收藏
GET /api/favorites/check 检查是否已收藏（参数：song_source / platform / external_id）
GET /api/favorites/stats 收藏统计信息 
POST /api/favorites
Content-Type: application/json

{
    "song_source": "online",
    "platform": "netease",
    "external_id": "186016",
    "title": "晴天",
    "artist": "周杰伦",
    "duration": 269
}

播放历史 API

基础路径：/api/history

方法 路径 说明
GET /api/history 播放历史列表（分页）
POST /api/history 添加播放记录
DELETE /api/history 清空所有历史
DELETE /api/history/{id} 删除单条历史记录

配置说明

配置文件：.env（从 .env.example 复制）

环境变量 说明 默认值
应用配置
APP_DEBUG 调试模式（开启后显示详细错误信息） false
APP_PAGE_SIZE 默认分页大小 20
数据库配置
DB_HOST 数据库主机地址 127.0.0.1
DB_DATABASE 数据库名称 music_api
音乐配置
MUSIC_LOCAL_PATH 本地音乐文件存放目录 C:/Music
MUSIC_DEFAULT_PLATFORM 默认在线音乐平台 netease
MUSIC_NETEASE_ENABLED 启用网易云平台 true
MUSIC_QQ_ENABLED 启用QQ音乐平台 true
MUSIC_KUGOU_ENABLED 启用酷狗音乐平台 true
MUSIC_CACHE_TTL 在线数据缓存过期时间（秒），0为不缓存 3600

© 2026 旧城云api | 滇ICP备2025075497号