声网内容中心提供在线 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 |
系统处理中。 |