声网内容中心提供在线 K 歌房场景所需歌曲内容,如歌曲、歌词、热歌榜等。内容由音乐合作方提供,如需进一步了解声网内容中心,请联系 sales@agora.io。
请联系 sales@agora.io 开通声网内容中心服务。
点歌 RESTful API 仅支持 HTTPS 协议。发送请求时,你需要通过 Basic HTTP 认证,并将生成的凭证填入 HTTP 请求头部的 Authorization 字段。具体生成 Authorization 字段的方法请参考 HTTP 基本认证。
所有的请求都发送给域名:api.sd-rtn.com。
所有的请求 URL 和请求包体内容都是区分大小写的。
内容中心 RESTful API 的公共参数及描述如下:
| 参数 | 类型 | 描述 |
|---|---|---|
appid |
(必填)String | 你的项目使用的 App ID,该 App ID 需要已开通内容中心权限。 |
requestId |
(必填)String | 本次请求的唯一标识。requestId 唯一。 |
| 参数 | 类型 | 描述 |
|---|---|---|
code |
Int64 | 响应状态码,0 表示请求成功。 |
msg |
String | 返回消息名称,ok 表示请求成功。 |
requestId |
String | 请求唯一标识,与请求包体中的 requestId 一致。 |
ext |
String | 预留字段 |
你可以调用该方法获取曲库中所有歌曲的列表。
路径参数
appid :详见公共参数。
查询参数
| 参数 | 类型 | 描述 |
|---|---|---|
requestId |
(必填)String | 本次请求的唯一标识。详见公共参数。 |
pageType |
(可选)Int64 | 翻页方式:0:(默认)下一页1:上一页 |
pageCode |
(可选) Int64 | 作为翻页锚点的歌曲编号。 |
size |
(可选)Int64 | 每页歌曲显示的最大数量。默认为 10,取值范围为 [1, 1000]。 |
status |
(可选) Int64 | 歌曲状态:1:(默认)已上架0:已下架-1:已删除9:全部状态 |
vendorId |
(可选) Int64 | 歌曲版权使用区域:2:全球版权 (除中国大陆、香港、澳门特别行政区) 3:中国大陆 |
highPartType |
(可选) Int64 | 副歌片段类型:0:(默认)机器及人工校验的副歌片段1:不需要副歌片段2:机器校验的副歌片段3:人工校验的副歌片段(推荐) |
如果响应状态码为 0,表示请求成功,响应包体中包含以下字段:
| 字段 | 类型 | 描述 |
|---|---|---|
data |
JSON | 信息详情。 |
msg |
String | 本次请求返回的消息。ok 表示请求成功。 |
requestId |
String | 请求 ID。本次请求的唯一标识。 |
ext |
String | 预留字段 |
data.pageType |
Int64 | 翻页方式:0:下一页1:上一页 |
data.pageCode |
Int64 | 翻页锚点的歌曲编号。 |
data.size |
Int | 每页歌曲显示的最大数量。 |
data.count |
Int | 本次请求返回的歌曲数量。 |
data.list |
JSON Array | 当前曲库中所有的歌曲列表。 |
data.list.songCode |
Int64 | 歌曲编号。 |
data.list.name |
String | 歌曲名称。 |
data.list.singer |
String | 歌手名称。 |
data.list.poster |
String | 歌手封面图片 URL。 |
data.list.lyricType |
Number Array | 歌词格式类型:0:xml 格式1:lrc 格式如果为空则表示没有歌词。 |
data.list.type |
Int64 | 歌曲资源类型:1:左声道伴奏,右声道原唱的单音轨歌曲。2:只有伴唱的单音轨歌曲。3:只有原唱的单音轨歌曲。4:多音轨歌曲。 |
data.list.duration |
Int64 | 歌曲时长(秒)。 |
data.list.status |
Int64 | 歌曲状态:1:已上架0:已下架-1:已删除 |
data.list.updateTime |
Int64 | 歌曲更新的 Unix 时间戳(秒)。 |
data.list.releaseTime |
String | 歌曲发布时间。 |
data.list.vendorId |
Int64 | 歌曲版权使用区域:2:全球版权 (除中国大陆、香港、澳门特别行政区) 3:中国大陆 |
data.list.pitchType |
Int64 | 歌曲是否支持演唱评分功能:1:歌曲支持演唱评分功能2:歌曲不支持演唱评分功能 |
data.list.highPartType |
Int64 | 副歌片段类型:0:(默认)机器及人工校验的副歌片段1:无副歌片段2:机器校验的副歌片段3:人工校验的副歌片段 |
data.list.highPart |
Array | 歌曲高潮片段 |
data.list.highPart.highStartTime |
Int64 | 歌曲高潮片段的开始时间点,单位毫秒。 |
data.list.highPart.highEndTime |
Int64 | 歌曲高潮片段的结束时间点,单位毫秒。 |
其他响应字段及说明详见公共参数。
如果返回的 HTTP 状态码非 0,表示请求失败。你可以参考响应状态码汇总表了解可能的原因。
curl 'https://api.sd-rtn.com/cn/v1.0/projects/{appid}/ktv-service/api/serv/songs?requestId=lzTZsruXVL3VUi2UVHHDTPE0PRvF8P4V&pageType=0&pageCode=6246262727281830&size=2' \
-H 'Authorization: {AuthorizationHeader}'
{
"code": 0,
"msg": "ok",
"requestId": "lzTZsruXVL3VUi2UVHHDTPE0PRvF8P4V",
"ext": "",
"data": {
"pageType": 0,
"size": 2,
"pageCode": 6246262727281830,
"count": 2,
"list": [
{
"songCode": 624626272728XXXX,
"name": "龙拳",
"singer": "周杰伦",
"poster": "https://accpic.sd-rtn.com/pic/release/jpg/1/7a8941/ChmFZ1S0immAVtSDAAODVRzMNHg454.jpg",
"duration": 274,
"lyricType": [
0,
1
],
"type": 1,
"releaseTime": "2014/11/27 9:32",
"status": 1,
"updateTime": 1638141088,
"vendorId": 3,
"pitchType": 1,
"lyricType": [
0,
1
],
"highPartType":3,
"highPart": [{
"highStartTime": 121122,
"highEndTime": 134213
}, {
"highStartTime": 154534,
"highEndTime": 162134
}],
},
{
"songCode": 624626272728XXXX,
"name": "最长的电影",
"singer": "周杰伦",
"poster": "https://accpic.sd-rtn.com/pic/release/jpg/1/7a8941/ChmFZ1S0immAVtSDAAODVRzMNHg454.jpg",
"duration": 230,
"lyricType": null,
"type": 1,
"releaseTime": "2014/11/27 9:32",
"status": 1,
"vendorId": 3,
"pitchType": 1,
"updateTime": 1635229782,
"highPartType":3,
"highPart": [{
"highStartTime": 121221,
"highEndTime": 132132
}, {
"highStartTime": 154534,
"highEndTime": 162134
}],
}
]
}
}
你可以调用该方法定期查询曲库中增量的歌曲。建议每隔 24 小时查询一次。
路径参数
appid :详见公共参数。
查询参数
| 参数 | 类型 | 描述 |
|---|---|---|
requestId |
(必填)String | 本次请求的唯一标识。详见公共参数。 |
lastUpdateTime |
(必填) Int64 | 最近一次更新曲库的 Unix 时间戳(秒)。 |
page |
(可选) Int64 | 目标页编号。默认为 1。取值范围为 [1, (232-1)]。 |
size |
(可选) Int64 | 目标页歌曲显示的最大数量。默认为 10,取值范围为 [1, 1000]。 |
status |
(可选)Int | 歌曲状态:1:(默认)已上架0:已下架-1:已删除9:全部状态 |
vendorId |
(可选) Int64 | 歌曲版权使用区域:2:全球版权 (除中国大陆、香港、澳门特别行政区) 3:中国大陆 |
highPartType |
(可选) Int64 | 副歌片段类型:0:(默认)机器及人工校验的副歌片段1:不需要副歌片段2:机器校验的副歌片段3:人工校验的副歌片段(推荐) |
注意
lastUpdateTime 的歌曲列表。lastUpdateTime 设置为 0,即获取曲库全部歌曲列表;如果不是第一次调用该方法,声网建议你将 lastUpdateTime 设置为前一次调用该方法获得的响应字段中 updateTime 的最大值。page 的 lastUpdateTime 设置为一致,否则会遗漏增量歌曲。如果响应状态码为 0,表示请求成功,响应包体中包含以下字段:
| 字段 | 类型 | 字段说明 |
|---|---|---|
data |
JSON | 信息详情。 |
msg |
String | 本次请求返回的消息,ok 表示请求成功。 |
requestId |
String | 请求 ID。本次请求的唯一标识。 |
ext |
String | 预留字段。 |
data.page |
Int64 | 当前页编号。 |
data.size |
Int64 | 当前页歌曲显示的最大数量。 |
data.count |
Int64 | 本次请求返回的歌曲数量。 |
data.list |
JSON Array | 本次请求的歌曲列表。 |
data.list.songCode |
Int64 | 歌曲编号。 |
data.list.name |
String | 歌曲名称。 |
data.list.singer |
String | 歌手名称。 |
data.list.poster |
String | 歌手封面图片 URL。 |
data.list.lyricType |
Number Array | 歌词格式类型:0:xml 格式1:lrc 格式如果为空则表示没有歌词。 |
data.list.type |
Int | 歌曲资源类型:1:左声道伴奏,右声道原唱的单音轨歌曲。2:只有伴唱的单音轨歌曲。3:只有原唱的单音轨歌曲。4:多音轨歌曲。 |
data.list.duration |
Int64 | 歌曲时长(秒)。 |
data.list.status |
Int | 歌曲状态:1:已上架0:已下架-1:已删除 |
data.list.updateTime |
Int64 | 歌曲更新的 Unix 时间戳(秒)。 |
data.list.releaseTime |
String | 歌曲发布时间。 |
data.list.vendorId |
Int64 | 歌曲版权使用区域:2:全球版权 (除中国大陆、香港、澳门特别行政区) 3:中国大陆 |
data.list.highPartType |
Int64 | 副歌片段类型:0:(默认)机器及人工校验的副歌片段1:无副歌片段2:机器校验的副歌片段3:人工校验的副歌片段 |
data.list.pitchType |
Int64 | 歌曲是否支持演唱评分功能:1:歌曲支持演唱评分功能2:歌曲不支持演唱评分功能 |
data.list.highPart |
Array | 歌曲高潮片段 |
data.list.highPart.highStartTime |
Int64 | 歌曲高潮片段的开始时间点,单位毫秒。 |
data.list.highPart.highEndTime |
Int64 | 歌曲高潮片段的结束时间点,单位毫秒。 |
其他响应字段及说明详见公共参数。
如果返回的 HTTP 状态码非 0,表示请求失败。你可以参考响应状态码汇总表了解可能的原因。
curl 'https://api.sd-rtn.com/cn/v1.0/projects/{appid}/ktv-service/api/serv/songs-incr?requestId=lzTZsruXVL3VUi2UVHHDTPE0PRvF8P4V&pageType=0&lastUpdateTime=1635229837&page=1&size=2' \
-H 'Authorization: {AuthorizationHeader}'
{
"code": 0,
"msg": "ok",
"requestId": "lzTZsruXVL3VUi2UVHHDTPE0PRvF8P4V",
"ext": "",
"data": {
"size": 2,
"page": 1,
"count": 2,
"list": [{
"songCode": 624626272729XXXX,
"name": "没有目的地爱了",
"singer": "杨千嬅",
"poster": "https://accpic.sd-rtn.com/pic/release/jpg/1/a35420/ChmFaVS9H2uARX7BAAFV0nstAAM724.jpg",
"duration": 267,
"lyricType": null,
"type": 2,
"releaseTime": "2014/12/15 22:13",
"vendorId": 3,
"pitchType": 1,
"status": 1,
"updateTime": 1635229838,
"highPartType":3,
"highPart": [{
"highStartTime": 121221,
"highEndTime": 132132
}, {
"highStartTime": 154534,
"highEndTime": 162134
}],
}, {
"songCode": 624626272729XXXX,
"name": "热血青年",
"singer": "杨千嬅",
"poster": "https://accpic.sd-rtn.com/pic/release/jpg/1/a35420/ChmFaVS9H2uARX7BAAFV0nstAAM724.jpg",
"duration": 411,
"lyricType": [
0
],
"type": 1,
"releaseTime": "2015/1/12 11:00",
"vendorId": 3,
"pitchType": 1,
"status": 1,
"updateTime": 1635229838,
"highPartType":3,
"highPart": [{
"highStartTime": 121221,
"highEndTime": 132132
}, {
"highStartTime": 154534,
"highEndTime": 162134
}],
}]
}
}
你可以调用该方法获取热歌榜单名称和类型。
路径参数
appid :详见公共参数。
查询参数
| 参数 | 类型 | 描述 |
|---|---|---|
requestId |
(必填)String | 本次请求的唯一标识。详见公共参数。 |
如果响应状态码为 0,表示请求成功,响应包体中包含以下字段:
| 字段 | 类型 | 字段说明 |
|---|---|---|
code |
Int64 | 响应状态码,0 表示请求成功。 |
msg |
String | 返回消息名称,ok 表示请求成功。 |
requestId |
String | 请求唯一标识,与请求包体中的 requestId 一致。 |
ext |
String | 预留字段。 |
data |
JSON | 信息详情。 |
data.list |
JSON Array | 热歌榜单信息列表。 |
data.list.hotName |
String | 热歌榜单名称。 |
data.list.hotType |
Int64 | 热歌榜单类型。 |
其他响应字段及说明详见公共参数。
如果返回的 HTTP 状态码非 0,表示请求失败。你可以参考状态码汇总表了解可能的原因。
curl 'https://api.sd-rtn.com/cn/v1.0/projects/{appid}/ktv-service/api/serv/hot-type?requestId=lzTZsruXVL3VUi2UVHHDTPE0PRvF8P4V' \
-H 'Authorization: {AuthorizationHeader}'
{
"code": 0,
"msg": "ok",
"requestId": "lzTZsruXVL3VUi2UVHHDTPE0PRvF8P4V",
"ext": "",
"data": {
list:[{
"hotName": "声网榜单",
"hotType": 1
}, {
"hotName": "新歌榜",
"hotType": 2
}]
}
}
你可以调用该方法获取热歌榜单详情。
- 热歌为日点播次数大于或等于 10 次的歌曲。
- 调用该方法获取的热歌榜单仅显示日点播次数前 100 的热歌,如果热歌数量少于 100 首则按实际数量显示。
- 每日 05:00 统计 0:00 之前的数据。
路径参数
appid :详见公共参数。
查询参数
| 参数 | 类型 | 描述 |
|---|---|---|
requestId |
(必填)String | 本次请求的唯一标识。详见公共参数。 |
hotType |
(可选)Int64 | 榜单类型:0:(默认)整体榜单2:新歌榜3:嗨唱推荐4:抖音热歌 5:古风热歌 6:KTV 必唱 |
如果响应状态码为 0,表示请求成功,响应包体中包含以下字段:
| 字段 | 类型 | 字段说明 |
|---|---|---|
data |
JSON | 信息详情。 |
msg |
String | 返回消息名称,ok 表示请求成功。 |
requestId |
String | 请求唯一标识,与请求包体中的 requestId 一致。 |
data.list |
JSON Array | 当前曲库中所有的歌曲列表。 |
data.list.songCode |
Int64 | 歌曲编号。 |
data.list.num |
Int64 | 点播次数。 |
ext |
String | 预留字段。 |
data.list.name |
String | 音乐资源名称。 |
data.list.singer |
String | 歌手名。 |
data.list.poster |
String | 音乐资源海报的下载地址。 |
data.list.lyricType |
JSON Array | 支持的歌词类型: |
data.list.pitchType |
Int64 | 歌曲是否支持演唱评分功能: |
data.list.type |
Int64 | 音乐资源类型: |
data.list.duration |
Int64 | 音乐资源总时长(秒)。 |
data.list.releaseTime |
String | 音乐资源发布的时间。 |
data.list.highPartType |
Int64 | 副歌片段类型:0:(默认)机器及人工校验的副歌片段1:无副歌片段2:机器校验的副歌片段3:人工校验的副歌片段 |
data.list.highPart |
JSON Array | 歌曲高潮片段。 |
data.list.highPart.highStartTime |
Int64 | 歌曲高潮片段的开始时间点,单位毫秒。 |
data.list.highPart.highEndTime |
Int64 | 歌曲高潮片段的结束时间点,单位毫秒。 |
其他响应字段及说明详见公共参数。
如果返回的 HTTP 状态码非 0,表示请求失败。你可以参考状态码汇总表了解可能的原因。
curl 'https://api.sd-rtn.com/cn/v1.0/projects/{appid}/ktv-service/api/serv/song-hot?requestId=lzTZsruXVL3VUi2UVHHDTPE0PRvF8P4V&hotType=1' \
437 + -H 'Authorization: {AuthorizationHeader}'
{
"code": 0,
"msg": "ok",
"requestId": "lzTZsruXVL3VUi2UVHHDTPE0PRvF8P4V",
"ext": "",
"data": {
"list": [{
"num":200,
"songCode": 624626272728XXXX,
"name": "龙拳",
"singer": "周杰伦",
"poster": "https://accpic.sd-rtn.com/pic/release/jpg/1/7a8941/ChmFZ1S0immAVtSDAAODVRzMNHg454.jpg",
"duration": 274,
"lyricType": [
0,
1
],
"type": 1,
"releaseTime": "2014/11/27 9:32",
"highPartType":3,
"highPart": [{
"highStartTime": 121221,
"highEndTime": 132132
}, {
"highStartTime": 154534,
"highEndTime": 162134
}],
}, {
"num":100,
"songCode": 624626272728XXXX,
"name": "七里香",
"singer": "周杰伦",
"poster": "https://accpic.sd-rtn.com/pic/release/jpg/1/7a8941/ChmFZ1S0immAVtSDAAODVRzMNHg454.jpg",
"duration": 274,
"lyricType": [
0,
1
],
"type": 1,
"releaseTime": "2014/11/27 9:32",
"highPartType":3,
"highPart": [{
"highStartTime": 121221,
"highEndTime": 132132
}, {
"highStartTime": 154534,
"highEndTime": 162134
}],
}, {
"num":10,
"songCode": 624626272728XXXX,
"name": "告白气球",
"singer": "周杰伦",
"poster": "https://accpic.sd-rtn.com/pic/release/jpg/1/7a8941/ChmFZ1S0immAVtSDAAODVRzMNHg454.jpg",
"duration": 274,
"lyricType": [
0,
1
],
"type": 1,
"releaseTime": "2014/11/27 9:32",
"highPartType":3,
"highPart": [{
"highStartTime": 121221,
"highEndTime": 132132
}, {
"highStartTime": 154534,
"highEndTime": 162134
}],
}]
}
}
为保障 REST 服务的高可用,避免因区域网络故障造成的服务不可用,声网提供切换域名的方案。
| 主域名 | 区域域名 | 地理区域 |
|---|---|---|
| api.sd-rtn.com | api-us-west-1.sd-rtn.com | 美国西部 |
| api-us-east-1.sd-rtn.com | 美国东部 | |
| api-ap-southeast-1.sd-rtn.com | 亚太东南 | |
| api-ap-northeast-1.sd-rtn.com | 亚太东北 | |
| api-eu-west-1.sd-rtn.com | 欧洲西部 | |
| api-eu-central-1.sd-rtn.com | 欧洲中部 | |
| api-cn-east-1.sd-rtn.com | 中国华东 | |
| api-cn-north-1.sd-rtn.com | 中国华北 | |
| api.agora.io | api-us-west-1.agora.io | 美国西部 |
| api-us-east-1.agora.io | 美国东部 | |
| api-ap-southeast-1.agora.io | 亚太东南 | |
| api-ap-northeast-1.agora.io | 亚太东北 | |
| api-eu-west-1.agora.io | 欧洲西部 | |
| api-eu-central-1.agora.io | 欧洲中部 | |
| api-cn-east-1.agora.io | 中国华东 | |
| api-cn-north-1.agora.io | 中国华北 |
| code | 说明 |
|---|---|
0 |
正常 |
1000 |
查询数据结果为空。 |
1001 |
操作异常。 |
1002 |
App ID 异常,如过期、关闭,该 App ID 未开通内容中心等,或白名单中的 IP 地址不合法。 |
1003 |
系统异常,请联系技术支持。 |
1004 |
系统繁忙,请稍后再试。 |
1005 |
参数错误。 |
1008 |
没有该歌曲资源权限。 |
1009 |
该歌曲资源已下架。 |
1010 |
系统处理中。 |