在 K 歌场景中，你可能需要根据搜索关键字来搜索歌曲。你可以使用 SearchMusics 这个 OpenAPI 来实现这一功能。

接口行为

你可以调用 SearchMusics 接口，指定搜索关键字，搜索曲库中符合筛选条件的歌曲。

调用接口

关于调用接口的服务地址、通信协议、字符编码和签名机制，参看调用 OpenAPI。

请求方式

使用 Post 方式发起请求。

请求参数

以下是接口特有的请求参数。关于其他公共请求参数，参看请求参数。

Query

参数名	类型	必填	示例值	描述
Action	String	是	`SearchMusics`	接口名称，本接口取值：`SearchMusics`
Version	String	是	`2020-12-01`	接口版本，本接口取值：`2020-12-01`

Body

参数名	类型	必填	示例值	描述
AppId	String	是	`Your_AppId`	应用的唯一标志
PageNum	Int	否	`1`	分页序号，默认值为`1`
PageSize	Int	否	`10`	每页歌曲数量，取值范围为`（0,100]`，默认值为`10`
Filters	Array of Int	否	`1`	过滤选项： `1`：过滤没有歌词的歌曲 `2`：过滤不支持打分的歌曲 `3`：过滤不支持伴唱切换的歌曲 `4`：过滤没有高潮片段的歌曲
KeyWord	String	否	`告白气球`	搜索关键字。匹配优先级为：精准歌曲名匹配 -> 精准歌手名匹配 -> 歌曲名模糊匹配

请求示例代码

Query

https://rtc.volcengineapi.com?Action=SearchMusics&Version=2020-12-01
postscript

Body

{
    "AppId": "Your_AppId",
    "PageSize": 10,
    "PageNum": 1,
    "KeyWord": "告白气球",
    "Filters": [
        1
    ]
}
json

返回调用结果

返回参数说明

返回结果参看 BaseResponse。

其中 Result 的结构如下：

参数名	类型	示例值	描述
Total	Int	`866`	按照搜索条件返回的歌曲总数
List	Array of List	返回歌曲详细信息

List

参数名	类型	示例值	描述
SongId	String	`Your_SongId`	歌曲 ID
Songname	String	`告白气球`	歌曲名称
Singer	String	`周杰伦`	歌曲歌手名
VendorId	Int	`1`	供应商 ID
VendorName	String	`Your_VendorName`	供应商名称
PosterUrl	String	`http://www.com/xxx.jpg`	歌曲封面地址
LyricType	Array of Int	`0`	歌词类型 `0`： `krc` `1`： `lrc` `[0,1]`：两种歌词均有。若为空，则表示为无歌词。
Duration	Int	`200`	歌曲时长，单位为秒
BgmType	Int	`2`	歌曲是否支持伴唱原唱切换。 `0`：不支持。 `1`：声道切换 `2`：音轨切换
PitchType	Int	`1`	歌曲是否支持打分。 `0`：不支持 `1`：支持
RecordType	Int	`1`	歌曲是否支持录制。 `0`：不支持 `1`：支持
Segment	String	`"[65.088, 87.168]"`	歌曲高潮部分
UpdateAt	Int	`1670518801`	歌曲更新时间戳，unix 时间，单位为秒
LyricUrl	LyricUrl		歌词文件地址。建议优先使用 krc、不存在时下可选择 lrc

LyricUrl

参数名	类型	示例值	描述
KrcUrl	String	`http://www.xxx.krc`	krc 歌词地址
LrcUrl	String	`http://www.xxx.lrc`	lrc 歌词地址
MidiUrl	String	`http://www.xxx.mid`	midi 文件地址

正常返回示例

返回值 Result 仅在请求成功时返回以上参数，失败时为空

{
    "ResponseMetadata": {
        "Action": "SearchMusics",
        "Version": "2020-12-01",
        "RequestId": "Your_RequestId",
        "Region": "cn-north-1",
        "Service": "rtc"
    },
    "Result": {
        "Total": 866,
        "List": [
            {
                "SongId": "Your_SongId",
                "BgmType": 2,
                "Duration": 186,
                "LyricType": [
                    1
                ],
                "PosterUrl": "http://www.com/xxx.jpg",
                "VendorName": "Your_VendorName",
                "Singer": "周杰伦",
                "Songname": "告白气球",
                "RecordType": 1,
                "PitchType": 1,
                "UpdateAt": 1670518801,
                "Segment": "[65.088, 87.168]",
                "VendorId": 1,
                "LyricUrl": {
                    "KrcUrl": "http://www.xxx.krc",
                    "LrcUrl": "http://www.xxx.lrc",
                    "MidiUrl": "http://www.xxx.mid"
                }
            }
        ]
    }
}
json