在 K 歌场景中，你可能需要按照筛选条件来查询歌曲列表。你可以使用 ListMusics 这个 OpenAPI 来实现这一功能。

接口行为

你可以调用 ListMusics 接口，指定过滤选项、歌曲新增或更新时间戳和歌曲 ID，查询歌曲列表。
如果你在控制台配置了曲库下架歌曲通知相关回调，在曲库中的歌曲下架后，你可以在配置的 URL 地址中获得通知。此时，你可以调用该接口获取最新歌曲列表。

调用接口

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

请求方式

使用 Post 方式发起请求。

请求参数

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

Query

参数名	类型	必填	示例值	描述
Action	String	是	`ListMusics`	接口名称，本接口取值：`ListMusics`
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`：过滤没有高潮片段的歌曲
LastUpdateTime	Int	否	`1839427200`	歌曲更新或新增时间戳，Unix 时间，单位为秒。表示筛选更新或新增时间大于等于 `LastUpdateTime` 的有效歌曲
SongIds	Array of string	否	`Your_SongId`	查询歌曲 ID，最多可以指定 200 个

请求示例代码

Query

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

Body

{
    "AppId": "Your_AppId",
    "PageNum": 1,
    "SongIds": [
        "Your_SongId"
    ],
    "PageSize": 10,
    "Filters": [
        1
    ],
    "LastUpdateTime": 1839427200
}
json

返回调用结果

返回参数说明

返回结果参看 BaseResponse。
其中 Result 的结构如下：

参数名	类型	示例值	描述
Total	Int	`866`	返回歌曲总数
List	Array of List	返回歌曲详情

正常返回示例

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

{
    "ResponseMetadata": {
        "Action": "ListMusics",
        "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