搜索 - 全民K歌IOT开放平台

搜索相关歌曲、歌手、MV等内容。
因为接口数据有过滤，所以每次请求20条时，返回的数据可能不足20条。
我们客户端都是这样处理，比如界面1页显示20条数据，我们就每一次请求30条数据。
当不足一页需要请求下一页时，通过上一页接口中返回的nextIndex和hasMore确认startPage，即下一页要从哪一条开始请求。
如果nextIndex没有，则只看hasMore。
if (it.nextIndex >= 0 && it.hasMore) {
startPage = it.nextIndex
}
直到has_more为false。
总数total不一定准，每次接口请求回来的总数都会刷新到界面上。
【2024.09.20更新】
新增语种分类lang_category参数，用于限定搜索的语种或者类别分类。目前支持的限定词有：
语种类：国语，粤语，闽南语，英语，日语，韩语，泰语，马来语，印尼语，越南语，菲律宾语
戏曲类：黄梅戏、京剧、粤剧、秦腔、越剧、潮剧、豫剧、沪剧、二人转

请求参数

Header 参数

X-Open-Access-Token

string

必需

access token

默认值:

X-Open-ID

string

openid

可选

默认值:

X-Open-App-ID

string

业务appid

必需

默认值:

Device-ID

string

可选

设备id，调用KtvSdk.getSdkImei()获取

Body 参数application/json

action

enum<integer>

必需

歌曲搜索方式: 1-拼音首字母搜索 2-中英文搜索。

枚举值:

content_flag

integer

必需

搜索内容：1-歌曲(0x1) 2-歌手(0x10) 4-MV(0x100). 如要搜索歌曲+歌手，则content_flag=0x1|0x10=0x11=3

enable_qc

integer

可选

搜索词允许纠错：0-允许(默认),1-不允许。如输入"刘得华"，允许纠错则搜索到的是刘德华的结果

filter_singer_area

enum<integer>

可选

按地区过滤歌手搜索结果; 0 -港台，1-内地，2 -日韩，3-欧美，4-其他，100-全部

枚举值:

01234100

filter_singer_type

enum<integer>

可选

按类型过滤歌手搜索结果; 0-男，1-女，2-组合 ,100-为全部

枚举值:

012100

page_num

integer

每页数量，最多30

可选

>= 1

start_page

integer

必需

分页搜索起始页，从1开始

>= 1

word

string

可选

搜索词。仅当搜索歌手时(content_flag=2)，word可为空，此时返回热门歌手，可结合filter_singer_area和filter_singer_type字段进行过滤

lang_category

string

可选

语种分类，action=2时有效。可以传日语、国语等词

ktv_safety_level

integer

可选

KTV合规库级别 0-全曲库 1-中曲库

with_chan_resource

boolean

可选

是否返回渠道独有曲库资源

merge_type

integer

可选

搜索歌曲聚集类型 0-全列表 1-折叠列表 2-折叠列表第一首。当action=2且ContentFlag&1>0且LangCategory为空生效

示例

{
    "start_page": 1,
    "page_num": 3,
    "word": "周杰伦",
    "content": 4,
    "action": 2
}

示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

返回响应

🟢200OK

application/json

Body

has_more

boolean

歌曲结果是否有更多

可选

mvs

array[object (protocol.MvInfo) {5}]

mv信息

可选

mv_cover

string

mv封面

可选

mv_mid

string

mv的mid

可选

mv_name

string

mv名称

可选

mv_singer_name

string

mv歌手名

可选

song_id

string

mv对应的歌曲Id

可选

singer_total

integer

歌手总数

可选

singers

array[object (protocol.SingerInfo) {5}]

歌手信息

可选

block_mask

integer

可选

屏蔽mask 非0时标识被屏蔽(为0时不返回) 1<<1为歌手屏蔽位

block_reason

string

屏蔽原因

可选

singer_cover

string

歌手图片

可选

singer_id

string

歌手唯一id

可选

singer_name

string

歌手名字

可选

songs

array[object (protocol.SongInfo) {31}]

歌曲信息

可选

1080_mv_cover_size

integer

可选

遮挡mv1080质量文件大小

1080_mv_size

integer

可选

mv1080质量文件大小

480_mv_cover_size

integer

可选

遮挡mv480质量文件大小

480_mv_size

integer

可选

mv480质量文件大小

720_mv_cover_size

integer

可选

遮挡mv720质量文件大小

720_mv_size

integer

可选

mv720质量文件大小

album_img

string

可选

歌曲专辑封面图片500*500

cp_status

integer

可选

版权状态，1:有版权， [-99,0]无版权，可播， <-300,无版权，不可播

has_hq

boolean

是否有HQ品质伴奏

可选

has_lyric

integer

可选

（废弃）是否有字幕(0-未知 1-无字幕 2-有字幕)

has_midi

boolean

唱歌时是否支持打分

可选

has_mv

boolean

是否有MV

可选

has_ori_song

boolean

歌曲是否有原唱

可选

language

integer

可选

语种：0-国语 1-粤语 2-闽南语 3-日语 4-韩语 5-英语 6-法语 7-其他 9-纯音乐

mv_cover

string

mv视频封面

可选

mv_has_lyric

boolean

可选

MV是否包含KTV歌词字幕：0-无，1-有（这种情况可以不用再加载伴奏歌词了）

mv_height

integer

mv视频高度

可选

mv_width

integer

mv视频宽度

可选

need_vip

boolean

是否需要VIP

可选

play_count

integer

歌曲播放量

可选

play_duration

integer

播放时长

可选

qqmusic_id

integer

可选

废弃(该字段返回0)

singer_id

string

歌手Id

可选

singer_name

string

歌手名称

可选

song_desc

string

歌曲描述

可选

song_id

string

歌曲编号

可选

song_lyric_mask

integer

可选

伴奏歌词标记，可按位判断与是否有对应的类型。(1:有qrc歌词)+(2:有lrc歌词)

song_name

string

歌曲名称

可选

song_type

integer

可选

歌曲类型 0-完整版 3-Live 6-Remix 100-和声

status

integer

可选

状态 0-下架 1-正常

tag_id_list

array[integer]

可选

tagid列表。参考《TagId对照表》

total_num

integer

歌曲总数

可选

group_songs

array [array]

可选

仅当req.merge_type==1生效时返回

object (protocol.SongInfo)

可选

示例

{
    "code": 0,
    "sub_code": 0,
    "msg": "请求成功",
    "data": {
        "singers": [
            {
                "singer_id": "0025NhlN2yWrP4",
                "singer_name": "周杰伦",
                "singer_cover": "https://y.gtimg.cn/music/photo_new/T001R500x500M0000025NhlN2yWrP4.jpg",
                "block_mask": 0,
                "block_reason": ""
            },
            {
                "singer_id": "004Frj3P4Emgu1",
                "singer_name": "周杰伦微博台",
                "singer_cover": "https://y.gtimg.cn/music/photo_new/T001R500x500M000004Frj3P4Emgu1.jpg",
                "block_mask": 0,
                "block_reason": ""
            },
            {
                "singer_id": "002Kzqzz3qM8Yq",
                "singer_name": "周周后援会",
                "singer_cover": "https://y.gtimg.cn/music/photo_new/T001R500x500M000002Kzqzz3qM8Yq.jpg",
                "block_mask": 0,
                "block_reason": ""
            }
        ],
        "songs": [
            {
                "status": 1,
                "song_id": "003rw1nY0qfb6w",
                "song_name": "爱情废柴",
                "album_img": "https://y.gtimg.cn/music/photo_new/T002R500x500M000003RMaRI1iFoYd.jpg",
                "singer_id": "0025NhlN2yWrP4",
                "singer_name": "周杰伦",
                "song_type": 0,
                "play_count": 14283295,
                "play_duration": 285,
                "has_mv": true,
                "has_hq": true,
                "has_ori_song": true,
                "has_midi": true,
                "mv_has_lyric": false,
                "cp_status": 1,
                "need_vip": false,
                "qqmusic_id": 0,
                "language": 0
            },
            {
                "status": 1,
                "song_id": "002FVh9i1aaAav",
                "song_name": "枫",
                "album_img": "https://y.gtimg.cn/music/photo_new/T002R500x500M0000024bjiL2aocxT.jpg",
                "singer_id": "0025NhlN2yWrP4",
                "singer_name": "周杰伦",
                "song_type": 0,
                "play_count": 33982686,
                "play_duration": 280,
                "has_mv": true,
                "has_hq": true,
                "has_ori_song": true,
                "has_midi": true,
                "mv_has_lyric": false,
                "cp_status": -1,
                "need_vip": false,
                "qqmusic_id": 0,
                "language": 0
            },
            {
                "status": 1,
                "song_id": "002l2FkL3o6F26",
                "song_name": "搁浅",
                "album_img": "https://y.gtimg.cn/music/photo_new/T002R500x500M000003DFRzD192KKD.jpg",
                "singer_id": "0025NhlN2yWrP4",
                "singer_name": "周杰伦",
                "song_type": 0,
                "play_count": 59001395,
                "play_duration": 262,
                "has_mv": true,
                "has_hq": true,
                "has_ori_song": true,
                "has_midi": true,
                "mv_has_lyric": false,
                "cp_status": -1,
                "need_vip": false,
                "qqmusic_id": 0,
                "language": 0
            }
        ],
        "mvs": null,
        "total_num": 15515,
        "has_more": true
    }
}