「音流」自定义 API

音流新版官网移至 music.aqzscn.cn，今后本页面内容将不再更新。

某些情况下，音乐服务提供的接口可能无法返回我们需要的信息，故提供自定义 API，高级用户可以自定义返回内容。

鉴权（可选）

配置项	位置	键	说明
授权信息	Request Header	Authorization

获取歌词

请求方式：GET

配置项	位置	键	说明
基础地址	URL	-	示例：https://example.com/lyrics
歌曲标题	URL Params	title	最终组装地址：https://example.com/lyrics?title=歌曲标题
歌手名	URL Params	artist
专辑名	URL Params	album
文件路径（可选）	URL Params	path	目前 Subsonic 和 Navidrome 都可以获取到文件路径，但不排除之后支持的协议中无法取得的情况，因此这个值可能为空。
时长（可选）	URL Params	duration	单位：秒，1.1.3 版本以上支持。
偏移（可选）	URL Params	offset	起始查询行，从 0 开始。1.1.6 版本以上支持，目前固定为 0 。
每页数量（可选）	URL Params	limit	1.1.6 版本以上支持，目前固定为 10 。

响应体

如果有歌词，直接返回歌词内容，没有时返回空，或设置响应状态码为 404.

从 1.1.6 版本开始支持分页获取歌词，在响应类型 content-type 设置为 application/json 后，将尝试把响应内容解析为 json 列表，结构如下：

[
    {
        "id": "<歌词id，用于与其他歌词去重>",
        "title": "<标题，可能与查询的标题不一致>",
        "artist": "<歌手，可能与查询的歌手不一致>",
        "lyrics": "<歌词文件内容>"
    },
    ...
]

确认歌词

适用于 1.2.0 及以上版本。

在用户手动点击歌词切换界面的保存按钮后触发。

请求方式：POST

配置项	位置	键	说明
基础地址	URL	-	示例：https://example.com/lyrics/confirm
内容类型	headers	content-type	application/json

请求体：

{
    "path": "文件路径",
    "title": "歌曲标题",
    "artist": "歌手",
    "album": "专辑",
    "lyrics": "待确认歌词内容",
    "lyricsId": "歌词id，可能为null"
}

响应码：若响应码不是20x，则提示用户「歌词确认异常」，没有异常则不提示信息。

获取封面

请求方式：GET

配置项	位置	键	说明
基础地址	URL	-	示例：https://example.com/covers
歌曲标题（可选）	URL Params	title	最终组装地址：https://example.com/covers?title=歌曲标题
歌手名	URL Params	artist
专辑名（可选）	URL Params	album

通过此接口，音流可控制传递的参数尝试获取不同类型的封面：

三者都传：获取歌曲封面
不传歌曲标题：获取专辑封面
只传歌手名：获取歌手图片

响应体

文件流。

歌曲详情

适用于 1.2.4 及以上版本，用于在浏览器中跳转到音乐服务对应的歌曲链接。

配置项	位置	键	说明
基础地址	URL	-	示例：https://example.com/details
歌曲路径	URL Params	title	最终组装地址：https://example.com/details?path=歌曲路径
目标	URL Params	target	目前固定为`detail`

示例配置：

路径替换的作用是当您的音乐服务在 Docker 部署时，识别到的路径可能和音乐文件实际路径是不同的，通过路径替换可以将第一个匹配到的字符串替换为 docker 服务可以识别的，即：

// 实际路径
/volume1/music/ff.flac
// 替换后路径
/app/media/ff.flac

目录CONTENT