获取客户端歌曲下载链接 - 新版

使用 /song/url/v1 接口获取的是歌曲试听 url, 非 VIP 账号最高只能获取 极高 音质，但免费类型的歌曲(fee == 0)使用本接口可最高获取Hi-Res音质的url。

接口信息

项目	值
接口地址	/song/download/url/v1
请求方式	GET / POST
需要登录	否
对应模块	song_download_url_v1
文档分类	歌曲与播放

请求参数

参数	类型	必填	默认值	说明
id	string	✅	-	音乐 id
level	string	✅	-	播放音质等级, 分为 standard => 标准,higher => 较高, exhigh=>极高,
lossless	string	✅	-	=>无损, hires=>Hi-Res, jyeffect => 高清环绕声, sky => 沉浸环绕声, dolby => 杜比全景声, jymaster => 超清母带

HTTP 示例

GET /song/download/url/v1?id=2155423468&level=hires

编程式调用

import { songDownloadUrlV1 } from 'hana-music-api';

const result = await songDownloadUrlV1({
  id: '2155423468',
  level: 'hires',
});

console.log(result.body);

返回内容

body.data 是一个对象，不是数组。声明了 id、url、code、level（实际给到的音质）、size（文件字节数），以及录制里出现的其他地址字段（码率、编码、md5、试听信息等）；只有 id、url、code 收紧，其余宽松。结构定义和类型是 SongDownloadUrlV1Body，与播放地址共用 SongUrlData 结构。

匿名请求会员歌 1409311773 的真实国内 IP 录制中，standard、higher、exhigh 均返回 data.code: -105、url: null、level: null、size: 0，表示当前身份没有下载权限；同一游客身份可以通过播放接口试听，但下载接口没有返回试听文件。无版权的下载录制为 data.code: -110，同样没有地址。顶层 body.code 和 HTTP 状态仍是 200，SDK 会正常返回这个正文，不会因条目里的负数返回码而拒绝 Promise。

下载前检查已声明的字段，不要用播放接口的试听地址代替下载失败的歌曲：

const { code, url, size } = result.body.data;
if (code !== 200 || url === null || size <= 0) {
  throw new Error(`无法下载歌曲，下载返回码：${code}`);
}
// 使用 url 下载，并按 size 核对文件字节数。

尚未录到下载接口返回试听片段，freeTrialInfo 不作类型声明，原样保留；也未录到下载接口的 404 或会员到期场景。完整的录制边界见 返回体结构。

补充说明

说明 : 使用 /song/url/v1 接口获取的是歌曲试听 url, 非 VIP 账号最高只能获取 极高 音质，但免费类型的歌曲(fee == 0)使用本接口可最高获取Hi-Res音质的url。

必选参数 : id : 音乐 id level: 播放音质等级, 分为 standard => 标准,higher => 较高, exhigh=>极高, lossless=>无损, hires=>Hi-Res, jyeffect => 高清环绕声, sky => 沉浸环绕声, dolby => 杜比全景声, jymaster => 超清母带

接口地址 : /song/download/url/v1

调用例子 : /song/download/url/v1?id=2155423468&level=hires