API说明

本文为您介绍AUI Kits在线K歌房的API说明。

登录

该接口客户可按自身业务需求实现，包括token的生成算法也是可以自定义，不过要确保生成及检验token使用相同的算法。

使用说明

• 请求协议：http/https

• 请求Path：/login

• 是否需要授权：否

• 请求Method：POST

• 请求ContentType：JSON

请求参数

返回数据

示例

请求示例

{
 "username":"usernamexxx",
 "password":"passwordxxxx"
}

正常返回示例

{
 "code": 200,
 "expire": "2023-02-28T14:38:06+08:00",
 "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2Nzc1NjYyODYsImlkIjoieXl5eSIsIm9yaWdfaWF0IjoxNjc3NDc5ODg2fQ.xxxxxx"
}

获取新IM建连的token

参考文档：服务端集成

使用说明

• 请求协议：http/https

• 请求Path：/api/ktv/token

• 是否需要授权：是

• 请求Method：POST

• 请求ContentType：JSON

请求参数

返回数据

示例

请求示例

{
 "user_id": "useridxxxx",
 "role":"admin"
}

正常返回示例

{
 "code": 200,
 "aliyun_im":{
    	"appid":"xxxx",
      "appsign":"xxxx",
   		"apptoken":"xxxxxxxxxxxxxxxxxx",
   		"auth":{
         "userid":"xxxx",
         "nonce":"xxxxx", // 可为空
          "timestamp":xxxxx,
          "role":"admin"
    	}
  }
}

创建KTV房间

使用说明

• 请求协议：http/https

• 请求Path：/api/ktv/create

• 是否需要授权：是

• 请求Method：POST

• 请求ContentType：JSON

请求参数

返回数据

示例

请求示例

{
 "title": "titlexxx",
 "notice": "noticexxx",
 "anchor":"房主userId",
 "anchor_nick":"房主nick",
 "extends":"{\"xx\":\"xxx\"}"
}

正常返回示例

{
    "code": 200,
    "anchor_id": "房主userId",
    "show_code": 65611075,
    "extends": "{\"xx\":\"xxx\"}",
    "updated_at": "2024-03-14T20:42:59",
    "created_at": "2024-03-14T20:42:59",
    "meetingInfo": "{\"members\":[{\"index\":1,\"joined\":false,\"user_id\":\"\"},{\"index\":2,\"joined\":false,\"user_id\":\"\"},{\"index\":3,\"joined\":false,\"user_id\":\"\"},{\"index\":4,\"joined\":false,\"user_id\":\"\"},{\"index\":5,\"joined\":false,\"user_id\":\"\"},{\"index\":6,\"joined\":false,\"user_id\":\"\"},{\"index\":7,\"joined\":false,\"user_id\":\"\"},{\"index\":8,\"joined\":false,\"user_id\":\"\"}]}",
    "id": "cfa4a59e90ab42cbaf708f218ad1f61d",
    "anchor_nick": "房主nick",
    "title": "互动KTV测试",
    "chat_id": "cfa4a59e90ab42cbaf708f218ad1f61d",
    "notice": "23232",
    "status": 1
}

分页获取KTV房间列表

使用说明

• 请求协议：http/https

• 请求Path：/api/ktv/list

• 是否需要授权：是

• 请求Method：POST

• 请求ContentType：JSON

请求参数

返回数据

示例

请求示例

{
 "page_size": 10,
 "page_num":1,
 "user_id": "useridxxxx"
}

正常返回示例

{
    "rooms": [
        {
            "id": "08a5d321d5f74d72bcbd87c5e41a57f4",
            "title": "hhh的房间",
            "status": 1,
            "created_at": "2024-03-14T21:06:52",
            "updated_at": "2024-03-14T21:06:52",
            "extends": "{\n  \"anchor_avatar\" : \"https:\/\/img.alicdn.com\/imgextra\/i2\/O1CN01VYKjf81Z1savmhLOr_!!6000000003135-0-tps-174-174.jpg\"\n}",
            "chat_id": "08a5d321d5f74d72bcbd87c5e41a57f4",
            "anchor_id": "hhh",
            "anchor_nick": "hhh",
            "show_code": 32611075,
            "metrics": {
                "online_count": 0
            }
        },
        {
            "id": "cfa4a59e90ab42cbaf708f218ad1f61d",
            "title": "互动聊天测试",
            "status": 1,
            "notice": "23232",
            "meetingInfo": "{\"members\":[{\"index\":1,\"join_time\":1710420349667,\"joined\":true,\"user_id\":\"assd\"},{\"index\":2,\"join_time\":1710420408513,\"joined\":true,\"user_id\":\"33334\"},{\"extends\":\"{\\\"nick\\\":\\\"xx33xx\\\",\\\"ava\\\":\\\"bb333bb\\\"}\",\"index\":3,\"join_time\":1710421936486,\"joined\":true,\"user_id\":\"333310\"},{\"index\":4,\"join_time\":1710420417941,\"joined\":true,\"user_id\":\"33335\"},{\"index\":5,\"join_time\":1710420423408,\"joined\":true,\"user_id\":\"33336\"},{\"index\":6,\"join_time\":1710420428932,\"joined\":true,\"user_id\":\"33337\"},{\"index\":7,\"join_time\":1710420436877,\"joined\":true,\"user_id\":\"33338\"},{\"index\":8,\"join_time\":1710420441424,\"joined\":true,\"user_id\":\"33339\"}]}",
            "created_at": "2024-03-14T20:42:59",
            "updated_at": "2024-03-14T20:42:59",
            "extends": "{\"xx\":\"xxx\"}",
            "chat_id": "cfa4a59e90ab42cbaf708f218ad1f61d",
            "anchor_id": "房主userId",
            "anchor_nick": "房主nick",
            "metrics": {
                "online_count": 0
            }
        },
        {
            "id": "cd6a4f31f3ad4593924c4081ddb9aba0",
            "title": "admin的房间",
            "status": 1,
            "created_at": "2024-03-14T19:24:29",
            "updated_at": "2024-03-14T19:24:29",
            "chat_id": "cd6a4f31f3ad4593924c4081ddb9aba0",
            "anchor_id": "admin",
            "anchor_nick": "admin",
            "show_code": 1612375,
            "metrics": {
                "online_count": 0
            }
        },
        {
            "id": "25f5346e1e1342289ebdf6c1ff9281a2",
            "title": "admin房间",
            "status": 1,
            "created_at": "2024-03-13T16:10:50",
            "updated_at": "2024-03-13T16:10:50",
            "chat_id": "25f5346e1e1342289ebdf6c1ff9281a2",
            "anchor_id": "admin",
            "anchor_nick": "admin",
            "show_code": 1112375,
            "metrics": {
                "online_count": 0
            }
        }
    ],
    "code": 200
}

获取单个聊天室

实现原理：参考/api/ktv/list实现。该接口也会返回已解散的房间信息

使用说明

• 请求协议：http/https

• 请求Path：/api/ktv/get

• 是否需要授权：是

• 请求Method：POST

• 请求ContentType：JSON

请求参数

返回数据

参考/api/ktv/list。只是将列表换为单个对象

示例

请求示例

{
 "id": "675e6783-0bac-4990-b6da-5aa890535029",
 "user_id": "Cedric8"
}

正常返回示例

{
    "code": 200,
    "anchor_id": "房主userId",
    "created_at": "2024-03-14T20:42:59",
    "title": "互动ktv测试",
    "chat_id": "cfa4a59e90ab42cbaf708f218ad1f61d",
    "extends": "{\"xx\":\"xxx\"}",
    "updated_at": "2024-03-14T20:42:59",
    "meetingInfo": "{\"members\":[{\"index\":1,\"join_time\":1710420349667,\"joined\":true,\"user_id\":\"assd\"},{\"index\":2,\"join_time\":1710420408513,\"joined\":true,\"user_id\":\"33334\"},{\"extends\":\"{\\\"nick\\\":\\\"xx33xx\\\",\\\"ava\\\":\\\"bb333bb\\\"}\",\"index\":3,\"join_time\":1710421936486,\"joined\":true,\"user_id\":\"333310\"},{\"index\":4,\"join_time\":1710420417941,\"joined\":true,\"user_id\":\"33335\"},{\"index\":5,\"join_time\":1710420423408,\"joined\":true,\"user_id\":\"33336\"},{\"index\":6,\"join_time\":1710420428932,\"joined\":true,\"user_id\":\"33337\"},{\"index\":7,\"join_time\":1710420436877,\"joined\":true,\"user_id\":\"33338\"},{\"index\":8,\"join_time\":1710420441424,\"joined\":true,\"user_id\":\"33339\"}]}",
    "id": "cfa4a59e90ab42cbaf708f218ad1f61d",
    "show_code": 232275,
    "metrics": {
        "online_count": 0
    },
    "anchor_nick": "房主nick",
    "notice": "23232",
    "status": 1
}

获取 RTC token

使用说明

• 请求协议：http/https

• 请求Path：/api/ktv/getRtcAuthToken

• 是否需要授权：是

• 请求Method：POST

• 请求ContentType：JSON

请求参数

返回数据

示例

请求示例

{
 "room_id": "675e6783-0bac-4990-b6da-5aa890535029",
 "user_id": "useridxxxx"
}

正常返回示例

{
 "code": 200,
 "authToken": "xxxxx",
 "timestamp": 12323XXXX
}

解散ktv房间

使用说明

• 请求协议：http/https

• 请求Path：/api/ktv/dismiss

• 是否需要授权：是

• 请求Method：POST

• 请求ContentType：JSON

请求参数

返回数据

示例

请求示例

{
 "id": "675e6783-0bac-4990-b6da-5aa890535029",
 "user_id": "useridxxxx"
}

正常返回示例

{
    "code": 200,
    "success": true
}

上麦

使用说明

• 请求协议：http/https

• 请求Path：/api/ktv/joinMic

• 是否需要授权：是

• 请求Method：POST

• 请求ContentType：JSON

请求参数

返回数据

示例

请求示例

{
    "id": "d34e834e029f44eb92db5868ee9316de",
    "user_id": "bbb",
    "extends":"{\"aaa\":\"bbb\"}"
}

正常返回示例

{
    "code": 200,
    "members": [
        {
            "user_id": "assd",
            "joined": true,
            "index": 1,
            "join_time": 1710420349667
        },
        {
            "user_id": "33334",
            "joined": true,
            "index": 2,
            "join_time": 1710420408513
        },
        {
            "extends": "{\"user_nick\":\"xx33xx\",\"user_avatrar\":\"bb333bb\"}",
            "user_id": "333310",
            "joined": true,
            "index": 3,
            "join_time": 1710421224316
        },
        {
            "user_id": "33335",
            "joined": true,
            "index": 4,
            "join_time": 1710420417941
        },
        {
            "user_id": "33336",
            "joined": true,
            "index": 5,
            "join_time": 1710420423408
        },
        {
            "user_id": "33337",
            "joined": true,
            "index": 6,
            "join_time": 1710420428932
        },
        {
            "user_id": "33338",
            "joined": true,
            "index": 7,
            "join_time": 1710420436877
        },
        {
            "user_id": "33339",
            "joined": true,
            "index": 8,
            "join_time": 1710420441424
        }
    ]
}

异常说明：

如果返回包括reason, 则表示有业务异常。此时需要通过reason来判断异常原因。

• reason = 1： 表示麦位已满

{
    "reason": 1,
    "code": 200,
    "desc": "麦位已满"
}

• reason = 2： 表示用户已经上麦

{
    "reason": 2,
    "code": 200,
    "desc": "用户已经上麦"
}

下麦

使用说明

• 请求协议：http/https

• 请求Path：/api/ktv/leaveMic

• 是否需要授权：是

• 请求Method：POST

• 请求ContentType：JSON

请求参数

返回数据

示例

请求示例

{
    "id": "cfa4a59e90ab42cbaf708f218ad1f61d",
    "user_id": "333310",
    "index":3
}

正常返回示例

{
    "code": 200,
    "members": [
        {
            "user_id": "assd",
            "joined": true,
            "index": 1,
            "join_time": 1710420349667
        },
        {
            "user_id": "33334",
            "joined": true,
            "index": 2,
            "join_time": 1710420408513
        },
        {
            "extends": "",
            "user_id": "",
            "joined": false,
            "index": 3
        },
        {
            "user_id": "33335",
            "joined": true,
            "index": 4,
            "join_time": 1710420417941
        },
        {
            "user_id": "33336",
            "joined": true,
            "index": 5,
            "join_time": 1710420423408
        },
        {
            "user_id": "33337",
            "joined": true,
            "index": 6,
            "join_time": 1710420428932
        },
        {
            "user_id": "33338",
            "joined": true,
            "index": 7,
            "join_time": 1710420436877
        },
        {
            "user_id": "33339",
            "joined": true,
            "index": 8,
            "join_time": 1710420441424
        }
    ]
}

获取连麦信息

使用说明

• 请求协议：http/https

• 请求Path：/api/ktv/getMeetingInfo

• 是否需要授权：是

• 请求Method：POST

• 请求ContentType：JSON

请求参数

返回数据

示例

请求示例

{
    "id": "cfa4a59e90ab42cbaf708f218ad1f61d"
}

正常返回示例

{
    "code": 200,
    "members": [
        {
            "user_id": "assd",
            "joined": true,
            "index": 1,
            "join_time": 1710420349667
        },
        {
            "user_id": "33334",
            "joined": true,
            "index": 2,
            "join_time": 1710420408513
        },
        {
            "extends": "",
            "user_id": "",
            "joined": false,
            "index": 3
        },
        {
            "user_id": "33335",
            "joined": true,
            "index": 4,
            "join_time": 1710420417941
        },
        {
            "user_id": "33336",
            "joined": true,
            "index": 5,
            "join_time": 1710420423408
        },
        {
            "user_id": "33337",
            "joined": true,
            "index": 6,
            "join_time": 1710420428932
        },
        {
            "user_id": "33338",
            "joined": true,
            "index": 7,
            "join_time": 1710420436877
        },
        {
            "user_id": "33339",
            "joined": true,
            "index": 8,
            "join_time": 1710420441424
        }
    ]
}

点歌

使用说明

• 请求协议：http/https

• 请求Path：/api/ktv/selectSong

• 是否需要授权：是

• 请求Method：POST

• 请求ContentType：JSON

请求参数

返回数据

返回正在播放及待播放的歌曲列表

示例

请求示例

{
    "user_id": "cfa4a59e90ab42cbaf708f218ad1f61d",
    "song_id": "xxxxxx",
    "room_id": "room_idxxx",
    "user_extends": "{\"user_avatrar\":\"xxxx\"}",
    "song_extends": "{\"xxxx\":\"xxxx\"}",
}

正常返回示例

{
    "code": 200,
    "success": true
}

异常说明：

如果返回包括reason, 则表示有业务异常。此时需要通过reason来判断异常原因。

• reason = 1： 表示重复点歌

{
    "reason": 1,
    "code": 200,
    "desc": "重复点歌"
}

播放歌曲

使用说明

• 请求协议：http/https

• 请求Path：/api/ktv/playSong

• 是否需要授权：是

• 请求Method：POST

• 请求ContentType：JSON

请求参数

返回数据

示例

请求示例

{
    "user_id": "cfa4a59e90ab42cbaf708f218ad1f61d",
    "room_id": "xxxxxx",
    "song_id": "songidxxxx"
}

正常返回示例

{
    "code": 200,
    "next_song_id": "song_id1234562"
}

异常说明：

如果返回包括reason, 则表示有业务异常。此时需要通过reason来判断异常原因。

• reason = 1： 表示无待播放歌曲

{
    "reason": 1,
    "code": 200,
    "desc": "无待播放歌曲"
}

• reason = 2： 表示歌曲不匹配

{
    "reason": 2,
    "code": 200,
    "desc": "歌曲不匹配"
}

• reason = 3： 表示无权限

{
    "reason": 3,
    "code": 200,
    "desc": "无权限"
}

• reason = 4：表示传入id为空，但列表中仍有待播放歌曲

{
    "reason": 4,
    "code": 200,
    "desc": "播放歌曲id为空，但仍有待播放歌曲"
}

删歌

使用说明

• 请求协议：http/https

• 请求Path：/api/ktv/deleteSong

• 是否需要授权：是

• 请求Method：POST

• 请求ContentType：JSON

请求参数

返回数据

示例

请求示例

{
    "user_id": "useridxxxx",
    "room_id": "xxxxxx",
    "song_ids": "songidxxxx,useridxxxx2",
    "operator": "useridxxxx"
}

正常返回示例

{
    "code": 200,
    "success": true
}

异常说明：

如果返回包括reason, 则表示有业务异常。此时需要通过reason来判断异常原因。

• reason = 1： 表示无此歌曲

{
    "reason": 1,
    "code": 200,
    "desc": "无此歌曲"
}

• reason = 2： 表示无权限

{
    "reason": 2,
    "code": 200,
    "desc": "无权限"
}

置顶歌曲

使用说明

• 请求协议：http/https

• 请求Path：/api/ktv/pinSong

• 是否需要授权：是

• 请求Method：POST

• 请求ContentType：JSON

请求参数

返回数据

示例

请求示例

{
    "user_id": "useridxxx",
    "song_id": "xxxxxx",
    "room_id": "room_idxxxxx",
    "operator": "useridxxx"
}

正常返回示例

{
    "code": 200,
    "success": true
}

异常说明：

如果返回包括reason, 则表示有业务异常。此时需要通过reason来判断异常原因。

• reason = 1： 表示无此歌曲

{
    "reason": 1,
    "code": 200,
    "desc": "无此歌曲"
}

• reason = 2： 表示无权限

{
    "reason": 2,
    "code": 200,
    "desc": "无权限"
}

获取点歌列表

说明：该接口只返回正在播放及待播放的歌曲列表

使用说明

• 请求协议：http/https

• 请求Path：/api/ktv/listSongs

• 是否需要授权：是

• 请求Method：POST

• 请求ContentType：JSON

请求参数

返回数据

示例

请求示例

{
    "room_id": "cfa4a59e90ab42cbaf708f218ad1f61d"
}

正常返回示例

{
    "code": 200,
    "songs": [
        {
            "user_id": "assd1",
            "song_id": "xxxxxx",
            "status": 2,
            "user_extends": "xxxxxx"
            "song_extends": "xxxxxx"
        },
        {
            "user_id": "assd2",
            "song_id": "xxxxxx",
            "status": 2,
            "user_extends": "xxxxxx"
            "song_extends": "xxxxxx"
        },
        {
            "user_id": "assd3",
            "song_id": "xxxxxx",
            "status": 3,
            "info": "xxxxxx"
        },
        {
            "user_id": "assd4",
            "song_id": "xxxxxx",
            "status": 3,
            "user_extends": "xxxxxx"
            "song_extends": "xxxxxx"
        },
              {
            "user_id": "assd5",
            "song_id": "xxxxxx",
            "status": 3,
            "user_extends": "xxxxxx"
            "song_extends": "xxxxxx"
        },
    ]
}

加入合唱

只能加入正在播放的歌曲

使用说明

• 请求协议：http/https

• 请求Path：/api/ktv/joinInSinging

• 是否需要授权：是

• 请求Method：POST

• 请求ContentType：JSON

请求参数

返回数据

示例

请求示例

{
    "room_id": "cfa4a59e90ab42cbaf708f218ad1f61d",
    "user_id": "useridxxxxx",
    "song_id": "songidxxxx"
}

正常返回示例

{
    "code": 200,
    "success": true
}

异常说明：

如果返回包括reason, 则表示有业务异常。此时需要通过reason来判断异常原因。

• reason = 1： 表示无正在播放歌曲

{
    "reason": 1,
    "code": 200,
    "desc": "无正在播放歌曲"
}

• reason = 2： 表示歌曲不匹配

{
    "reason": 2,
    "code": 200,
    "desc": "歌曲不匹配"
}

• reason = 3： 表示无需重复加入

{
    "reason": 2,
    "code": 200,
    "desc": "无需重复加入"
}

退出合唱

使用说明

• 请求协议：http/https

• 请求Path：/api/ktv/leaveSinging

• 是否需要授权：是

• 请求Method：POST

• 请求ContentType：JSON

请求参数

返回数据

示例

请求示例

{
    "room_id": "cfa4a59e90ab42cbaf708f218ad1f61d",
    "user_id": "useridxxxxx",
    "song_id": "songidxxxx"
}

正常返回示例

{
    "code": 200,
    "success": true
}

异常说明：

如果返回包括reason, 则表示有业务异常。此时需要通过reason来判断异常原因。

• reason = 1： 表示无正在播放歌曲

{
    "reason": 1,
    "code": 200,
    "desc": "无正在播放歌曲"
}

• reason = 2： 表示歌曲不匹配

{
    "reason": 2,
    "code": 200,
    "desc": "歌曲不匹配"
}

• reason = 3： 表示未加入合唱

{
    "reason": 2,
    "code": 200,
    "desc": "未加入合唱"
}

获取当前房间的合唱信息

使用说明

• 请求协议：http/https

• 请求Path：/api/ktv/getSinging

• 是否需要授权：是

• 请求Method：POST

• 请求ContentType：JSON

请求参数

返回数据

示例

请求示例

{
    "room_id": "cfa4a59e90ab42cbaf708f218ad1f61d"
}

正常返回示例

{
    "code": 200,
    "members": [
        {
            "user_id": "22222222",
            "join_time": 1712907655333
        },
        {
            "user_id": "22222223",
            "join_time": 1712907683501
        }
    ]
}

说明：主唱即为点歌的user_Id，不会展示在该列表中