文档中心
在线 K 歌房
Console Agora.io 社区 提交工单
简体中文
search-icon

Agora 内容中心

更新时间 2022/05/14 11:21:01

Agora 内容中心提供在线 K 歌房场景所需歌曲内容，如歌曲、歌词、MV、热歌榜等。内容由音乐合作方提供，如需进一步了解 Agora 内容中心，请联系 sales@agora.io。

点歌流程即调用 RESTful API 从内容中心获取曲库所有歌曲及相关信息，再获取指定歌曲及相关信息。你还可以通过调用 RESTful API 使用 Agora 内容中心的进阶功能。

目前曲库内歌曲由咪咕音乐提供。使用该曲库，你需要在前端展示“歌曲来自咪咕音乐”字样。目前仅支持在中国大陆地区的 K 歌场景中使用咪咕音乐的曲库。

前提条件

开通服务

在控制台开通内容中心权限并完成相关配置。

  1. 登录控制台，点击左侧导航栏项目管理进入项目管理页面。

  2. 选择需要开通内容中心的项目，点击编辑按钮进入编辑项目页面。

  3. 在编辑项目页面的实时互动拓展能力模块找到内容中心，点击启用。

  4. 选择内容中心状态为启用，仔细阅读弹窗提示，添加白名单 IP，点击保存。成功开启后，启用按钮会切换为配置按钮，用于配置内容中心。

    请将你在跑通示例项目过程中运行 LeanCloudHelp.py 脚本的服务器 IP 地址添加到白名单中。

HTTP 认证

点歌 RESTful API 仅支持 HTTPS 协议。发送请求时，你需要通过 Basic HTTP 认证，并将生成的凭证填入 HTTP 请求头部的 Authorization 字段。具体生成 Authorization 字段的方法请参考 HTTP 基本认证。

实现点歌功能

通过获取曲库所有歌曲列表和获取指定歌曲两个步骤来实现点歌。

数据格式

所有的请求都发送给域名：api.agora.io。

  • 请求：请求的格式详见下面各个 API 中的示例
  • 响应：响应内容的格式为 JSON

所有的请求 URL 和请求包体内容都是区分大小写的。

公共参数

内容中心 RESTful API 的公共参数及描述如下：

请求参数

参数 类型 描述
appid （必填）String 你的项目使用的 App ID，该 App ID 需要已开通内容中心权限。
requestId （必填）String 本次请求的唯一标识。
  • 必须设置为 32 位字符串，支持大写字母、小写字母、数字、"_"（下划线）、"-"（中划线），不区分大小写。
  • 一个项目下 requestId 唯一。
    		•

    响应参数

    参数 类型 描述
    code Int64 响应状态码，0 表示请求成功。
    msg String 返回消息名称，ok 表示请求成功。
    requestId String 请求唯一标识，与请求包体中的 requestId 一致。
    ext String 预留字段

    步骤一 获取曲库所有歌曲列表

    首先，你需要调用该方法获取曲库中所有歌曲的列表。

    HTTP 请求

    • 方法：GET
    • 接入点：cn/v1.0/projects/{appid}/ktv-service/api/serv/songs

    路径参数

    appid ：详见公共参数。

    查询参数

    参数 类型 描述
    requestId （必填）String 本次请求的唯一标识。详见公共参数。
    pageType （可选）Int64 翻页方式：
  • 0：（默认）下一页
  • 1：上一页
    		•
    pageCode （可选） Int64 作为翻页锚点的歌曲编号。
  • 第一次获取曲库无需设置该参数。
  • 默认为当前页歌曲列表第一首歌曲的编号。
    		•
    size （可选）Int64 每页歌曲显示的最大数量。默认为 10，取值范围为 [1, 1000]。
    status （可选） Int64 歌曲状态：
  • 1：（默认）已上架
  • 0：已下架
  • -1：已删除
  • 9：全部状态
    		•
    songType （可选） Int64 歌曲资源类型：
  • 1：左声道伴奏，右声道原唱的单音轨纯音频歌曲。
  • 2：只有伴唱的单音轨纯音频歌曲。
  • 3：只有原唱的单音轨纯音频歌曲。
  • 4：既有多音轨纯音频又有多音轨MV资源的歌曲。
  • 5：只有多音轨 MV 资源的歌曲。
    默认获取所有类型。
    		•
    vendorId （可选） Int64 歌曲版权方编号：
  • 1：咪咕
  • 2：鳌拜
    默认获取所有版权方。
    		•

    HTTP 响应

    如果响应状态码为 0，表示请求成功，响应包体中包含以下字段：

    字段 类型 描述
    data JSON 信息详情。
    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：既有多音轨纯音频又有多音轨MV资源的歌曲。
  • 5：只有多音轨 MV 资源的歌曲。
    		•
    data.list.duration Int64 歌曲时长（秒）。
    data.list.updateTime Int64 歌曲更新的 Unix 时间戳（秒）。
    data.list.releaseTime String 歌曲发布时间。
    data.list.vendorId Int64 歌曲版权方编号：
  • 1：咪咕
  • 2：鳌拜
    		•
    data.list.pitchType Int64 歌曲是否支持演唱评分功能：
  • 1：歌曲支持演唱评分功能
  • 2：歌曲不支持演唱评分功能
    		•
    data.list.mv JSON Array 当前曲库中所有的 MV（Music Video）信息列表。
    data.list.mv.resolution String MV 的分辨率，目前支持分辨率包括 480P、720P 和 1080P。
    data.list.mv.bw String MV 的带宽，单位为 Kbps。

    其他响应字段及说明详见公共参数。
    如果返回的 HTTP 状态码非 0，表示请求失败。你可以参考响应状态码汇总表了解可能的原因。

    请求示例

    curl 'https://api.agora.io/cn/v1.0/projects/{appid}/ktv-service/api/serv/songs?requestId=XXXXXX&pageType=0&pageCode=123&size=2' \
-H 'Authorization: {AuthorizationHeader}'

    响应示例

    {
    "code": 0,
    "msg": "ok",
    "requestId": "XXXXXX",
    "ext": "",
    "data": {
        "pageType": 0,
        "size": 2,
        "pageCode": 6246262727281830,
        "count": 2,
        "list": [
            {
                "songCode": 123,
                "name": "龙拳",
                "singer": "周杰伦",
                "poster": "https://XXXX.jpg",
                "duration": 274,
                "lyricType": [
                    0,
                    1
                ],
                "type": 1,
                "releaseTime": "2014/11/27 9:32",
                "status": 1,
                "updateTime": 1638141088,
                "mv": [
                    {
                        "resolution": "720P",
                        "bw": "0"
                    },
                    {
                        "resolution": "480P",
                        "bw": "0"
                    }
                ]
            },
            {
                "songCode": 456,
                "name": "最长的电影",
                "singer": "周杰伦",
                "poster": "https://XXXX.jpg",
                "duration": 230,
                "lyricType": null,
                "type": 1,
                "releaseTime": "2014/11/27 9:32",
                "status": 1,
                "updateTime": 1635229782,
                "mv": null
            }
        ]
    }
}

    步骤二 获取指定歌曲

    获取曲库中所有歌曲列表后，你需要调用该方法获取指定歌曲 URL。

    HTTP 请求

    • 方法：GET
    • 接入点：cn/v1.0/projects/{appid}/ktv-service/api/serv/song-url

    路径参数

    appid ：详见公共参数。

    查询参数

    参数 类型 描述
    requestId （必填）String 本次请求的唯一标识。详见公共参数。
    songCode （必填） Int64 歌曲编号，从获取曲库歌曲列表方法的响应包体中获取。
    lyricType （可选） Int 歌词格式类型：
  • 0：（默认）xml
  • 1：lrc
    		•

    HTTP 响应

    如果响应状态码为 0，表示请求成功，响应包体中包含以下字段：

    字段 类型 字段说明
    data JSON 信息详情。
    data.playUrl String 歌曲 URL 地址。
    data.lyric String 歌词 URL 地址。
    data.lyricType Int64 歌词格式类型：
  • 0：xml
  • 1：lrc
    		•
    data.expiryTime Int64 歌曲 URL 过期的 Unix 时间戳（秒）
    内容中心支持歌曲防盗链功能，歌曲 URL 仅在 30 分钟内有效，一旦过期需重新获取。

    其他响应字段及说明详见公共参数。
    如果返回的 HTTP 状态码非 0，表示请求失败。你可以参考响应状态码汇总表了解可能的原因。

    请求示例

    curl 'https://api.agora.io/cn/v1.0/projects/{appid}/ktv-service/api/serv/song-url?requestId=XXXXXX&songCode=123&lyricType=0' \
-H 'Authorization: {AuthorizationHeader}'

    响应示例

    {
    "code": 0,
    "msg": "ok",
    "requestId": "XXXXXX",
    "ext": "",
    "data": {
        "playUrl": "https://XXXX.mp3",
        "lyric": "https://XXXX.zip",
        "lyricType": 0,
        "expiryTime": 1638786637
    }
}

    进阶功能

    获取增量歌曲列表

    你可以调用该方法定期查询曲库中增量的歌曲。建议每隔 24 小时查询一次。

    HTTP 请求

    • 方法：GET
    • 接入点：cn/v1.0/projects/{appid}/ktv-service/api/serv/songs-incr

    路径参数

    appid ：详见公共参数。

    查询参数

    参数 类型 描述
    requestId （必填）String 本次请求的唯一标识。详见公共参数。
    lastUpdateTime （必填） Int64 最近一次更新曲库的 Unix 时间戳（秒）。
    page （可选） Int64 目标页编号。默认为 1。取值范围为 [1, (232-1)]。
    size （可选） Int64 目标页歌曲显示的最大数量。默认为 10，取值范围为 [1, 1000]。
    status （可选）Int 歌曲状态：
  • 1：（默认）已上架
  • 0：已下架
  • -1：已删除
  • 9：全部状态
    		•
    songType （可选） Int64 歌曲资源类型：
  • 1：左声道伴奏，右声道原唱的单音轨纯音频歌曲。
  • 2：只有伴唱的单音轨纯音频歌曲。
  • 3：只有原唱的单音轨纯音频歌曲。
  • 4：既有多音轨纯音频又有多音轨MV资源的歌曲。
  • 5：只有多音轨 MV 资源的歌曲。
    默认为所有类型。
    		•
    vendorId （可选） Int64 歌曲版权方编号：
  • 1：咪咕
  • 2：鳌拜
    默认获取所有版权方。
    		•

    注意

    • 调用该方法，你会得到指定页更新时间大于 lastUpdateTime 的歌曲列表。
    • 如果你是第一次调用该方法，Agora 建议你将 lastUpdateTime 设置为 0，即获取曲库全部歌曲列表；如果不是第一次调用该方法，Agora 建议你将 lastUpdateTime 设置为前一次调用该方法获得的响应字段中 updateTime 的最大值。
    • 你需要将每个 page 的 lastUpdateTime 设置为一致，否则会遗漏增量歌曲。

    HTTP 响应

    如果响应状态码为 0，表示请求成功，响应包体中包含以下字段：

    字段 类型 字段说明
    data JSON 信息详情。
    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：既有多音轨纯音频又有多音轨MV资源的歌曲。
  • 5：只有多音轨 MV 资源的歌曲。
    		•
    data.list.duration Int64 歌曲时长（秒）。
    data.list.status Int 歌曲状态：
  • 1：已上架
  • 0：已下架
  • -1：已删除
    		•
    data.list.updateTime Int64 歌曲更新的 Unix 时间戳（秒）。
    data.list.releaseTime String 歌曲发布时间。
    data.list.vendorId Int64 歌曲版权方编号：
  • 1：咪咕
  • 2：鳌拜
    		•
    data.list.pitchType Int64 歌曲是否支持演唱评分功能：
  • 1：歌曲支持演唱评分功能
  • 2：歌曲不支持演唱评分功能
    		•
    data.list.mv JSON Array 当前曲库中所有的 MV（Music Video）信息列表。
    data.list.mv.resolution String MV 的分辨率，目前支持分辨率包括 480P、720P 和 1080P。
    data.list.mv.bw String MV 的带宽，单位为 Kbps。

    其他响应字段及说明详见公共参数。
    如果返回的 HTTP 状态码非 0，表示请求失败。你可以参考响应状态码汇总表了解可能的原因。

    请求示例

    curl 'https://api.agora.io/cn/v1.0/projects/{appid}/ktv-service/api/serv/songs-incr?requestId=XXXXXX&pageType=0&lastUpdateTime=1635229837&page=1&size=2' \
-H 'Authorization: {AuthorizationHeader}'

    响应示例

    {
    "code": 0,
    "msg": "ok",
    "requestId": "XXXXXX",
    "ext": "",
    "data": {
        "size": 2,
        "page": 1,
        "count": 2,
        "list": [
            {
                "songCode": 123,
                "name": "没有目的地爱了",
                "singer": "杨千嬅",
                "poster": "https://XXXX.jpg",
                "duration": 267,
                "lyricType": null,
                "type": 2,
                "releaseTime": "2014/12/15 22:13",
                "status": 1,
                "updateTime": 1635229838,
                "mv": null
            },
            {
                "songCode": 456,
                "name": "热血青年",
                "singer": "杨千嬅",
                "poster": "https://XXXX.jpg",
                "duration": 411,
                "lyricType": [
                    0
                ],
                "type": 1,
                "releaseTime": "2015/1/12 11:00",
                "status": 1,
                "updateTime": 1635229838,
                "mv": null
            }
        ]
    }
}

    获取录制文件上传参数

    调用该方法获取录制文件上传参数，并通过第三方云存储接口上传录制文件至 Agora 内容中心。支持整体上传和追加上传两种上传方式。

    HTTP 请求

    • 方法：GET
    • 接入点：/cn/v1.0/projects/{appid}/ktv-service/api/serv/recording-sign

    路径参数

    appid ：详见公共参数。

    查询参数

    参数 类型 描述
    requestId （必填）String 本次请求的唯一标识。详见公共参数。
    songCode （必填）Int64 歌曲编号，从获取曲库歌曲列表方法的响应包体中获取。
    appendPosition （可选）Int64 当以追加的方式上传录制文件时，指定从录制文件何处追加内容。单位为字节。
  • 不得超过 314572800 字节。
  • 首次追加上传，需要将该值设为 0。
  • 你可以通过获取录制文件已上传的内容长度方法获取追加位置。
  • 整体上传无需设置该参数。
    • 详见第三方云存储文档。
    contentLength （必填）Int64 本次上传的内容大小。单位字节，取值范围 [1024,104857600]。
    contentMd5 （必填）String 本次上传内容的二进制数组的 MD5 值。
  • 根据录制文件的二进制数组计算并生成 base64 编码字符串，详见第三方云存储文档。
  • 得到 base64 编码字符串后需要进行特殊字符处理，即将 "+"（英文加号） 改为 "-"（英文减号），将 "/"（英文斜杠） 改为 "_"（英文下划线）。
    		•
    title （可选）String 待上传录制文件的标题。长度必须在 64 个字符以内。默认为空。仅 recordingCode 为 0（首次上传录制文件） 时传入有效。
    describe （可选）String 待上传录制文件的具体描述。长度必须在 64 个字符以内。默认为空。仅 recordingCode 为 0 （首次上传录制文件） 时传入有效。
    duration （必填）String 待上传录制文件的时长，单位为秒。
    fileExtension （必填）String 待上传录制文件的扩展名，必须为小写，例如：mp3、mp4、mkv。
    recordingCode （可选）Int64 录制文件编号，一个录制文件的唯一标识符。默认值为 0，即首次上传录制文件。
    非首次上传录制文件，需要将该字段设置为首次上传响应包体中获取的值，并确保 songCode、fileExtension 字段与首次上传录制文件时请求包体中传入的字段值一致。

    HTTP 响应

    如果响应状态码为 0，表示请求成功，响应包体中包含以下字段：

    字段 类型 描述
    data JSON 信息详情。
    data.recordingCode Int64 录制文件编号，一个录制文件的唯一标识符。与请求包体中的 recordingCode 一致。
    data.uploadUrl String Array 本次上传的录制文件的 URL 地址数组。
    data.uploadMethod String 上传录制文件的请求方式，包括 PUT、POST。
    uploadHeader String 上传录制文件的请求头部所需的字符串。后续处理如下：
    1. 将得到的字符串进行特殊字符处理得到标准的 base64 编码字符串，即将 "-"（英文减号）改为 "+"（英文加号），将 "_"（英文下划线）改为 "/"（英文斜杠）。
    2. 将 base64 编码字符串进行 base64 解码后得到数对键-值对，组成上传录制文件的请求头部。请求头组成及说明详见第三方云存储文档。
    经过以上处理后得到的键-值对必须全部用于上传录制文件的请求头部，且顺序不分先后。

    其他响应字段及说明详见公共参数。
    如果返回的 HTTP 状态码非 0，表示请求失败。你可以参考状态码汇总表了解可能的原因。

    请求示例

    curl 'https://api.agora.io/cn/v1.0/projects/{appid}/ktv-service/api/serv/recording-sign?requestId=XXXXXX&songCode=123&fileExtension=mp3&contentMd5=Z98dxTgihP6LTNNypH5zNg==&contentLength=4007843&duration=276' \
-H 'Authorization: {AuthorizationHeader}'

    响应示例

    {
    "code": 0,
    "msg": "ok",
    "requestId": "XXXX",
    "ext": "",
    "data": {
        "recordingCode": 1234,
        "uploadUrl": [
            "https://XXXX.mp3"
        ],
        "uploadMethod": "PUT",
          //解码后："Content-Length=4007843&Content-MD5=Z98dxTgihP6LTNNypH5zNg==&Date=Mon, 06 Dec 2021 10:19:10 GMT&Authorization=OSS LTAI5tLyafHCXXXXXXm8g:ONfXeZiW6oYr0u8jRaZjYY86FKg="
        "uploadHeader": "Q29udGVudC1MZW5ndGg9NDAwNzg0MyZDb250XXXXXXXXXXXXXFRnaWhQNkxUTk55cEg1ek5nPT0mRGF0ZT1Nb24sIDA2IERlYyAyMDIxIDEwOjE5OjEwIEdNVCZBdXRob3JpemF0aW9uPU9TUyBMVEFJNXRMeWFmSEMxZm5FWUdodGZtOGc6T05mWGVaaVc2b1lyMHU4alJhWmpZWTg2RktnPQ=="
    }
}

    获取录制文件已上传的内容长度

    调用该方法获取一个录制文件已经上传内容的长度。

    HTTP 请求

    • 方法：GET
    • 接入点：/cn/v1.0/projects/{appid}/ktv-service/api/serv/recording-uploaded-info

    路径参数

    appid ：详见公共参数。

    查询参数

    参数 类型 描述
    requestId （必填）String 本次请求的唯一标识。详见公共参数。
    recordingCode （必填）Int64 录制文件编号，一个录制文件的唯一标识符。请确保与获取录制文件上传参数方法的响应包体中的 recordingCode 一致。

    HTTP 响应

    如果响应状态码为 0，表示请求成功，响应包体中包含以下字段：

    字段 类型 描述
    data JSON 信息详情。
    data.contentLength Int64 录制文件已上传的内容长度。单位为字节。

    其他响应字段及说明详见公共参数。
    如果返回的 HTTP 状态码非 0，表示请求失败。你可以参考状态码汇总表了解可能的原因。

    请求示例

    curl 'https://api.agora.io/cn/v1.0/projects/{appid}/ktv-service/api/serv/recording-uploaded-info?requestId=XXXXXX&recordingCode=1234' \
-H 'Authorization: {AuthorizationHeader}'

    响应示例

    {
    "code": 0,
    "msg": "ok",
    "requestId": "XXXXXX",
    "ext": "",
    "data": {
        "contentLength": 2007843
    }
}

    录制文件上传结束通知

    当录制文件上传结束，你需要调用该方法通知 Agora 内容中心。

    HTTP 请求

    • 方法：POST
    • 接入点：/cn/v1.0/projects/{appid}/ktv-service/api/serv/recording-finish

    路径参数

    appid ：详见公共参数。

    查询参数

    参数 类型 描述
    requestId （必填）String 本次请求的唯一标识。详见公共参数。
    recordingCode （必填）Int64 录制文件编号，一个录制文件的唯一标识符。
    songCode （必填）Int64 歌曲编号，从获取曲库歌曲列表方法的响应包体中获取。
    uploadRetryTimes （必填）Int64 上传重试次数，未重试则为 0。
    uploadState （必填）Int 上传状态：
  • 1：上传成功
  • 2：上传取消
  • 3：上传失败
    		•
    uploadFailMsg （可选）String 上传失败时的报错信息

    HTTP 响应

    • 如果响应状态码为 0，表示请求成功，响应包体中包含字段详见公共参数。
    • 如果返回的 HTTP 状态码非 0，表示请求失败。你可以参考状态码汇总表了解可能的原因。

    请求示例

    curl 'https://api.agora.io/cn/v1.0/projects/{appid}/ktv-service/api/serv/recording-finish?requestId=XXXXXX&recordingCode=1234&songCode=123&uploadState=1&uploadRetryTimes=0' \
-H 'Authorization: {AuthorizationHeader}'

    响应示例

    {
    "code": 0,
    "msg": "ok",
    "requestId": "XXXXXX",
    "ext": ""
}

    获取已上传录制文件列表

    你可以调用该方法获取已上传的录制文件列表。

    HTTP 请求

    • 方法：GET
    • 接入点：/cn/v1.0/projects/{appid}/ktv-service/api/serv/recordings

    路径参数

    appid ：详见公共参数。

    查询参数

    参数 类型 描述
    requestId （必填）String 本次请求的唯一标识。详见公共参数。
    lastUpdateTime （必填）Int64 最近一次上传录制文件的 Unix 时间戳（秒）。设置为 0 代表获取当前项目下所有已上传的录制文件列表。
    page （可选）Int64 目标页编号。默认为 1。取值范围为 [1, (232-1)]。
    size （可选）Int64 目标页录制文件显示的最大数量。默认为 10，取值范围为 [1, 1000]。
    status （可选）Int 录制文件状态：
  • 1：（默认）可用
  • 0：暂不可用，可以随时恢复
  • -1：销毁且不可恢复
  • 9：全部状态
    		•

    注意：

    • 调用该方法，你会得到指定编号页上传时间大于 lastUpdateTime 的录制文件列表。
    • 如果你是第一次调用该方法，Agora 建议你将 lastUpdateTime 设置为 0，即获取全部录制文件列表；如果不是第一次调用该方法，Agora 建议你将 lastUpdateTime 设置为前一次调用该方法获得的响应字段中 updateTime 的最大值。
    • 你需要将每个 page 的 lastUpdateTime 设置为一致，否则会遗漏增量录制文件。

    HTTP 响应

    如果响应状态码为 0，表示请求成功，响应包体中包含以下字段：

    字段 类型 字段说明
    data JSON 信息详情。
    data.page Int64 当前页编号。
    data.size Int64 当前页录制文件显示的最大数量。
    data.count Int64 本次请求返回的录制文件数量。
    data.list JSON Array 录制文件列表。
    data.recordingCode Int64 录制文件编号，一个录制文件的唯一标识符。与请求包体中的 recordingCode 一致。
    data.title String 录制文件的标题。
    data.describe String 录制文件的具体描述。
    data.list.songCode Int64 歌曲编号。
    data.list.duration Int64 录制文件时长（秒）。
    data.list.status Int 录制文件状态：
  • 1：可用
  • 0：暂不可用，可以随时恢复
  • -1：销毁且不可恢复
    		•
    data.list.updateTime Int64 录制文件更新的 Unix 时间戳（秒）。
    • 其他响应字段及说明详见公共参数。
    • 如果返回的 HTTP 状态码非 0，表示请求失败。你可以参考状态码汇总表了解可能的原因。

    请求示例

    curl 'https://api.agora.io/cn/v1.0/projects/{appid}/ktv-service/api/serv/recordings?requestId=XXXXXX&pageType=0&lastUpdateTime=1635229837&page=1&size=2' \
-H 'Authorization: {AuthorizationHeader}'

    响应示例

    {
    "code": 0,
    "msg": "ok",
    "requestId": "XXXXXX",
    "ext": "",
    "data": {
        "size": 2,
        "page": 1,
        "count": 1,
        "list": [
            {
                "recordingCode": 1234,
                "title": "",
                "describe": "",
                "duration": 276,
                "status": 1,
                "songCode": 123,
                "updateTime": 1638757896
            }
        ]
    }
}

    修改录制文件信息

    你可以调用该方法修改录制文件信息。

    HTTP 请求

    • 方法：PUT
    • 接入点：/cn/v1.0/projects/{appid}/ktv-service/api/serv/recording-update

    路径参数

    appid ：详见公共参数。

    查询参数

    参数 类型 描述
    requestId （必填）String 本次请求的唯一标识。详见公共参数。
    recordingCode （必填）Int64 录制文件编号，一个录制文件的唯一标识符。
    title （必填）String 录制文件的标题。
    describe （可选）String 录制文件的具体描述。

    HTTP 响应

    • 如果响应状态码为 0，表示请求成功，响应包体中包含字段详见公共参数。
    • 如果返回的 HTTP 状态码非 0，表示请求失败。你可以参考状态码汇总表了解可能的原因。

    请求示例

    curl 'https://api.agora.io/cn/v1.0/projects/{appid}/ktv-service/api/serv/recording-update?requestId=XXXXXX&recordingCode=1234&title=合唱晴天' \
-H 'Authorization: {AuthorizationHeader}'

    响应示例

    {
    "code": 0,
    "msg": "ok",
    "requestId": "XXXXXX",
    "ext": ""
}

    修改录制文件状态

    你可以调用该方法修改录制文件状态。

    HTTP 请求

    • 方法：PUT
    • 接入点：/cn/v1.0/projects/{appid}/ktv-service/api/serv/recording-status

    路径参数

    appid ：详见公共参数。

    查询参数

    参数 类型 描述
    requestId （必填）String 本次请求的唯一标识。详见公共参数。
    recordingCode （必填）Int64 录制文件编号，一个录制文件的唯一标识符。
    status （必填）Int 录制文件当前状态：
  • 1：可用
  • 0：暂不可用，可以随时恢复
  • -1：销毁且不可恢复
    		•

    HTTP 响应

    • 如果响应状态码为 0，表示请求成功，响应包体中包含字段详见公共参数。
    • 如果返回的 HTTP 状态码非 0，表示请求失败。你可以参考状态码汇总表了解可能的原因。

    请求示例

    curl 'https://api.agora.io/cn/v1.0/projects/{appid}/ktv-service/api/serv/recording-status?requestId=XXXXXX&recordingCode=1234&status=0' \
-H 'Authorization: {AuthorizationHeader}'

    响应示例

    {
    "code": 0,
    "msg": "ok",
    "requestId": "XXXXXX",
    "ext": ""
}

    获取录制文件播放地址

    你可以调用该方法获取录制文件播放地址。

    HTTP 请求

    • 方法：GET
    • 接入点：/cn/v1.0/projects/{appid}/ktv-service/api/serv/recording-url

    路径参数

    appid ：详见公共参数。

    查询参数

    参数 类型 描述
    requestId （必填）String 本次请求的唯一标识。详见公共参数。
    recordingCode （必填）Int64 录制文件编号，一个录制文件的唯一标识符。
    lyricType （可选）Int 歌词格式类型：
  • 0：（默认）xml
  • 1：lrc
    		•

    HTTP 响应

    如果响应状态码为 0，表示请求成功，响应包体中包含以下字段：

    字段 类型 字段说明
    data JSON 信息详情。
    data.recordingUrl String 录制文件 URL 地址。
    data.lyric String 歌词 URL 地址。
    data.lyricType Int 歌词格式类型：
  • 0：xml
  • 1：lrc
    		•
    data.expiryTime String 录制文件和歌词 URL 地址过期的 Unix 时间戳（秒）。

    其他响应字段及说明详见公共参数。
    如果返回的 HTTP 状态码非 0，表示请求失败。你可以参考状态码汇总表了解可能的原因。

    请求示例

    curl 'https://api.agora.io/cn/v1.0/projects/{appid}/ktv-service/api/serv/recording-url?requestId=XXXXXX&recordingCode=1234&lyricType=0' \
-H 'Authorization: {AuthorizationHeader}'

    响应示例

    {
    "code": 0,
    "msg": "ok",
    "requestId": "XXXXXX",
    "ext": "",
    "data": {
        "recordingUrl": "https://XXXX.mp3",
        "lyric": "https://XXXX.zip",
        "lyricType": 0,
        "expiryTime": 1638789332
    }
}

    获取热歌榜单

    你可以调用该方法获取热歌榜单。

    • 热歌为日点播次数大于或等于 10 次的歌曲。
    • 调用该方法获取的热歌榜单仅显示日点播次数前 100 的热歌，如果热歌数量少于 100 首则按实际数量显示。
    • 每日 05:00 统计 0:00 之前的数据。

    HTTP 请求

    • 方法：GET
    • 接入点：/cn/v1.0/projects/{appid}/ktv-service/api/serv/song-hot

    路径参数

    appid ：详见公共参数。

    查询参数

    参数 类型 描述
    requestId （必填）String 本次请求的唯一标识。详见公共参数。
    hotType （可选）Int 榜单类型：
  • 0：（默认）该项目的热歌榜单
  • 1：内容中心的热歌榜单
  • 3：嗨唱推荐
  • 4：抖音热歌
  • 5：古风热歌
  • 6：KTV 必唱
    		•

    HTTP 响应

    如果响应状态码为 0，表示请求成功，响应包体中包含以下字段：

    字段 类型 字段说明
    data JSON 信息详情。
    data.list JSON Array 热歌榜单列表。
    data.list.songCode Int64 歌曲编号。
    data.list.num Int64 点播次数。

    其他响应字段及说明详见公共参数。
    如果返回的 HTTP 状态码非 0，表示请求失败。你可以参考状态码汇总表了解可能的原因。

    请求示例

    curl 'https://api.agora.io/cn/v1.0/projects/{appid}/ktv-service/api/serv/song-hot?requestId=XXXXXX&hotType=1' \
-H 'Authorization: {AuthorizationHeader}'

    响应示例

    {
    "code": 0,
    "msg": "ok",
    "requestId": "XXXXXX",
    "ext": "",
    "data": {
        "list": [
            {
                "songCode": 123,
                "num": 157
            },
            {
                "songCode": 456,
                "num": 149
            },
            {
                "songCode": 789,
                "num": 145
            },
            {
                "songCode": 012,
                "num": 133
            },
            {
                "songCode": 345,
                "num": 132
            },
            {
                "songCode": 678,
                "num": 123
            },
            {
                "songCode": 901,
                "num": 99
            },
            {
                "songCode": 234,
                "num": 95
            },
            {
                "songCode": 567,
                "num": 84
            },
            {
                "songCode": 890,
                "num": 73
            }
        ]
    }
}

    获取 MV 播放地址

    你可以获取 MV 播放地址。

    HTTP 请求

    • 方法：GET
    • 接入点：/cn/v1.0/projects/{appid}/ktv-service/api/serv/mv-url

    路径参数

    appid ：详见公共参数。

    查询参数

    参数 类型 描述
    requestId （必填）String 本次请求的唯一标识。详见公共参数。
    songCode （必填）Int64 歌曲编号，从获取曲库歌曲列表方法的响应包体中获取。
    resolution （可选）String MV 分辨率，包括 480P、720P、1080P。不设置则默认为所有分辨率。
    data.lyricType （可选）Int 歌词格式类型：
  • 0：（默认）xml
  • 1：lrc
    		•

    HTTP 响应

    如果响应状态码为 0，表示请求成功，响应包体中包含以下字段：

    字段 类型 字段说明
    data JSON 信息详情。
    data.bgmUrl String BGM（Background Music） 播放 URL 地址。
    data.lyric String 歌词 URL 地址。
    data.lyricType Int 歌词格式类型：
  • 0：xml
  • 1：lrc
    		•
    data.mvList JSON ARRAY MV 信息列表。
    data.mvList.resolution String MV 分辨率。
    data.mvList.mvUrl String MV 播放 URL 地址 。
    data.expiryTime Int64 BGM、歌词、MV URL 过期的 Unix 时间戳（秒）。

    其他响应字段及说明详见公共参数。
    如果返回的 HTTP 状态码非 0，表示请求失败。你可以参考状态码汇总表了解可能的原因。

    请求示例

    curl 'https://api.agora.io/cn/v1.0/projects/{appid}/ktv-service/api/serv/mv-url?requestId=XXXXXX&songCode=123&lyricType=0&resolution=480P' \
-H 'Authorization: {AuthorizationHeader}'

    响应示例

    {
    "code": 0,
    "msg": "ok",
    "requestId": "XXXXXX",
    "ext": "",
    "data": {
        "playUrl": "https://XXXX.mp3",
        "lyric": "https://XXXX.zip",
        "lyricType": 0,
        "expiryTime": 1638789797,
        "mvList": [
            {
                "resolution": "480P",
                "mvUrl": "https://XXXX.mkv"
            }
        ]
    }
}

    参考信息

    响应状态码汇总表

    code 说明
    0 正常
    1000 查询数据结果为空。
    1001 操作异常。
    1002 App ID 异常，如过期、关闭，该 App ID 未开通内容中心等，或白名单中的 IP 地址不合法。
    1003 系统异常，请联系技术支持。
    1004 系统繁忙，请稍后再试。
    1005 参数错误。
    1008 没有该歌曲资源权限。
    1009 该歌曲资源已下架。