logo
控制台登录/注册
文档
服务端 API
在线 KTV
API 概览
调用方式
获取标签列表
根据标签获取歌曲
搜索提示
搜索歌曲
搜索多版权方的歌曲
获取榜单歌曲
查询歌曲信息
查询歌曲的版权信息
获取歌曲的歌词
获取歌词分片
获取伴奏高潮时间点
判断是否存在伴奏高潮片段
获取歌曲附加信息
全局返回码
当前页

根据标签获取歌曲

描述

本接口调用需通过 获取标签列表 中的标签 ID，可获取对应的歌曲 ID、歌曲名、歌曲专辑、以及版权相关信息等。

说明

相比原有 歌单 接口，本接口歌曲资源更丰富，且支持动态更新。因此，ZEGO 推荐开发者使用本接口获得歌曲列表相关内容。

接口原型

  • 请求方法：GET
  • 请求地址：https://ktv-api.zego.im/?Action=DescribeTagSongs
  • 传输协议：HTTPS
  • 调用频率限制：200 次/秒

请求参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表请参考 调用方式 - 公共请求参数。

说明

在线 KTV 服务端接口的公共请求参数与实时音视频、实时语音的不同，包含了 VendorId（版权方 ID），请务必阅读上述参考文档。

参数类型是否必选描述
TagIdString是标签 ID，通过 获取标签列表 接口获取。
PageNumber是第几页，从 1 开始。
Filter[]Array of Number否过滤选项。
  • 1：过滤不包含词曲版权的歌曲
  • 3：过滤没有逐字歌词的歌曲
  • 4：过滤没有音高线的歌曲

请求示例

https://ktv-api.zego.im/?Action=DescribeTagSongs
&TagId=1107
&Page=1
&Filter[]=1
&Filter[]=3
&<公共请求参数>

以上示例表示：根据标签 ID 是 1107，通过过滤选项 1 和 3，筛选出有词曲版权且含有歌词的歌曲，展示列表第一页的内容。

响应参数

参数类型描述
CodeNumber返回码。
MessageString请求结果的说明信息。
RequestIdString请求 ID。
DataObject响应结果，详情可见 Data。
Data
参数类型描述
SongsArray of Object歌曲列表，详情可见 Songs。
Songs
参数类型描述
SongId String 歌曲 ID。
SongName String 歌曲名。
SingerName String 歌手名。
SingerImg String 歌手头像。
AlbumName String 歌曲所属专辑名。
AlbumImg String 专辑封面。
AlbumImgMini String 专辑封面 100px 左右。
AlbumImgSmall String 专辑封面 300px 左右。
AlbumImgMedium String 专辑封面 500px 左右。
DurationNumber歌曲时长，单位：毫秒。
HasClipNumber是否具有长分片高潮片段资源。
  • 0：否
  • 1：是

VendorId 为 2 时，不会返回此字段。

VendorIdNumber歌曲的版权方。版权方的详细信息，请联系 ZEGO 商务人员咨询。
PitchAbilityNumber是否具有音高线。
  • 1：有
  • 2：没有

仅当 VendorId 为 2 时，才会返回此字段。

Copyright Object 版权信息，详情可见 Copyright。
参数类型描述
SongLyricNumber是否有词曲版权，可以唱。一般有词曲版权则表示有录音版权。
  • 0：否
  • 1：是
RecordingNumber是否有录音版权，可以播放。
  • 0：否
  • 1：是
ChannelNumber歌曲渠道。
  • 若 channel 为 其他值，表示其他渠道歌曲。
  • 若 channel 为 0，需要在 UI 界面展示 logo 标志。开发者可通过 本链接 下载相关 logo 资源。UI 界面示例如下：

响应示例

{
    "Code": 0,
    "Message": "succeed",
    "RequestId": "1a6d02a8-66ba-455f-9e05-fe77da6a1f14",
    "Data": {
        "Songs": [
            {
                "SingerImg": "http://singerimg.kugou.com/uploadpic/softhead/150/20210107/20210107101003717.jpg",
                "AlbumImg": "http://imge.kugou.com/stdmusic/150/20160907/20160907184908526143.jpg",
                "AlbumImgMini": "http://imge.kugou.com/stdmusic/150/20160907/20160907184908526143.jpg",
                "AlbumImgSmall": "http://imge.kugou.com/stdmusic/240/20160907/20160907184908526143.jpg",
                "AlbumImgMedium": "http://imge.kugou.com/stdmusic/480/20160907/20160907184908526143.jpg",
                "SongId": "28341435",
                "SongName": "朋友的酒",
                "SingerName": "李晓杰",
                "AlbumName": "老大",
                "Duration": 250000,
                "HasClip": 1,
                "VendorId": 2,  // 歌曲的版权方。版权方的详细信息，请联系 ZEGO 商务人员咨询
                "PitchAbility": 1, //仅当 VendorId 为 2 时，才会返回此字段
                "Copyright": {
                    "SongLyric": 1,
                    "Recording": 1,
                    "Channel": 0
                }
            }
        ]
    }
}

返回码

以下仅列出了接口业务逻辑相关的部分返回码，完整返回码请参考 全局返回码。

返回码说明处理建议
320000004参数非法。请根据 Message 提示判断非法参数，调整对应参数值。
320010000AppId 不可用请联系 ZEGO 技术支持开通版权音乐服务。
320010001不支持的付费类型。请联系 ZEGO 技术支持开通版权音乐对应的付费类型。
  • 按次计费
320050000系统错误。请联系 ZEGO 技术支持。
320050002系统繁忙。请稍后重试。
320050003未定义的引擎错误。请联系 ZEGO 技术支持。
320050004引擎内部错误。请联系 ZEGO 技术支持。

Previous

获取标签列表

Next

搜索提示

当前页

返回到顶部