> For the complete documentation index, see [llms.txt](https://polyv.gitbook.io/document/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://polyv.gitbook.io/document/docs/live/api/channel/operate/add_account.md).
# 创建单个角色
### 接口描述
```
1、创建频道的助教或嘉宾角色
助教：使用助教管理后台，能够观看直播、参与互动、进行聊天室管理，发送图文直播，监控直播等操作
嘉宾：讲师和嘉宾可同时讲一堂课，支持连麦互动
2、接口URL中的{channelId}为频道号
3、接口支持https协议
```
### 接口URL
```
http://api.polyv.net/live/v2/channelAccount/{channelId}/add
```
### 请求方式
```
POST
```
### 接口约束
1、接口同时支持HTTP 、HTTPS ，建议使用HTTPS 确保接口安全，接口调用有频率限制，[详细请查看](https://git.polyv.net/help-center/document-center/-/blob/master/live/api/limit/README.md)
2、每个直播频道最多可以创建150个助教，嘉宾最大数量为16
3、创建嘉宾需要设置频道连麦人数，开启连麦功能
### 请求参数描述
| 参数名 | 必选 | 类型 | 说明 |
| --------- | ----- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| appId | true | String | 账号appId【详见[获取密钥](https://git.polyv.net/help-center/document-center/-/blob/master/live/api/getSecretKey/README.md)】 |
| timestamp | true | Long | 当前13位毫秒级时间戳，3分钟内有效 |
| sign | true | String | 签名，为32位大写的MD5值,`生成签名的appSecret密钥作为通信数据安全的关键信息，严禁保存在客户端直接使用，所有API都必须通过客户自己服务器中转调用POLYV服务器获取响应数据`【详见[签名生成规则](https://git.polyv.net/help-center/document-center/-/blob/master/live/api/buildSign/README.md)】 |
| role | false | String | 默认不传为助教
Assistant：助教
Guest：嘉宾
|
| nickname | false | String | 昵称，默认随机生成昵称 |
| password | false | String | 角色密码 |
| actor | false | String | 头衔，默认为助教 |
| avatar | false | String | 头像，默认初始头像 |
### 示例
```requestUrl
http://api.polyv.net/live/v2/channelAccount/2191541/add
```
表单参数：
```requestUrl
actor=%E5%8A%A9%E6%95%99&role=Assistant&appId=frlr1zazn3&nickname=%E5%88%98%E8%80%81%E5%B8%88&sign=F9953D904B2177872672A693F53D86EB&avatar=https%3A%2F%2Fs1.videocc.net%2Fdefault-img%2Favatar%2Fassistant.png×tamp=1621841707106
```
### 响应参数描述
| 参数名 | 类型 | 说明 |
| ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| code | Integer | 响应状态码，200为成功返回，非200为失败【详见[全局错误说明](https://git.polyv.net/help-center/document-center/-/blob/master/live/api/errorInfo/README.md)】 |
| status | String | 响应状态文本信息 |
| message | String | 响应描述信息，当code为400或者500的时候，辅助描述错误原因 |
| data | Object | 请求失败时为空，请求成功时为频道的信息 【详见[data字段描述](https://git.polyv.net/help-center/document-center/-/blob/master/live/api/channel/operate/add_account.md?id=data字段描述)】 |
#### data字段描述
| 参数名 | 类型 | 说明 |
| ---------------- | ------- | ---------------------------------------------- |
| account | String | 助教/嘉宾账号 |
| userId | String | POLYV用户ID，和保利威官网一致，获取路径：官网->登录->直播（开发设置） |
| channelId | String | 频道号 |
| passwd | String | 角色密码 |
| nickname | String | 角色名称 |
| stream | String | 角色流名，单独使用无效 |
| status | String | 角色状态
Y：开启
N：关闭
|
| createdTime | Long | 创建角色时间 |
| lastModified | Long | 角色最后修改时间 |
| sort | Integer | 频道角色序号 |
| avatar | String | 角色头像 |
| actor | String | 角色头衔 |
| pageTurnEnabled | String | 是否拥有翻页权限，只能一个助教有，仅支持三分屏场景
Y：是
N：否
|
| notifyEnabled | String | 是否拥有发布公告权限
Y：是
N：否
|
| checkinEnabled | String | 是否拥有开启签到权限
Y：是
N：否
|
| voteEnabled | String | 是否拥有发起投票权限
Y：是
N：否
|
| lotteryEnabled | String | 是否拥有抽奖权限
Y：是
N：否
|
| role | String | 角色
Assistant：助教
Guest：嘉宾
|
| chatListEnabled | String | 助教页在线列表显示开关
Y：开启
N：关闭
|
| chatAuditEnabled | String | 助教聊天审核
Y：开启
N：关闭
|
| monitorEnabled | String | 助教监播开关
Y：开启
N：关闭
|
| roundTourEnabled | String | 助教轮巡开关
Y：开启
N：关闭
|
| watchLockEnabled | String | 锁定直播间功能开关
Y：开启
N：关闭
|
### Java请求示例
快速接入基础代码请下载相关依赖源码， [点击下载源代码](https://git.polyv.net/help-center/document-center/-/blob/master/third_res/util.zip) ,下载后加入到自己的源码工程中即可。测试用例中的**HttpUtil.java 和 LiveSignUtil.java** 都包含在下载文件中。
> 强烈建议您使用[直播Java SDK](https://git.polyv.net/help-center/document-center/-/blob/master/live/java/README.md)完成API的功能对接，直播Java SDK 对API调用逻辑、异常处理、数据签名、HTTP请求线程池进行了统一封装和优化。
```java
private static final Logger log = LoggerFactory.getLogger(ChannelOperateTest.class);
/**
* 创建角色
* @throws IOException
* @throws NoSuchAlgorithmException
*/
@Test
public void testAddAccount() throws IOException, NoSuchAlgorithmException {
//公共参数,填写自己的实际参数
String appId = super.appId;
String appSecret = super.appSecret;
String userId = super.userId;
String timestamp = String.valueOf(System.currentTimeMillis());
//业务参数
String url = "https://api.polyv.net/live/v2/channelAccount/%s/add";
String channelId = "2149813";
String role = "Assistant";
String nickname = "刘老师";
String actor = "助教";
String avatar = "https://s1.videocc.net/default-img/avatar/assistant.png";
url = String.format(url, channelId);
Map requestMap = new HashMap<>();
requestMap.put("appId", appId);
requestMap.put("timestamp", timestamp);
requestMap.put("role", role);
requestMap.put("nickname", nickname);
requestMap.put("actor", actor);
requestMap.put("avatar", avatar);
requestMap.put("sign", LiveSignUtil.getSign(requestMap, appSecret));
String response = HttpUtil.postFormBody(url, requestMap);
log.info("测试创建角色，返回值：{}", response);
//do somethings
}
```
### 响应示例
系统全局错误说明详见[全局错误说明](https://git.polyv.net/help-center/document-center/-/blob/master/live/api/errorInfo/README.md)
成功示例
```json
{
"code":200,
"status":"success",
"message":"",
"data":{
"account":"0072149710",
"userId":"1b448be323",
"channelId":2149710,
"passwd":"xxxxxx",
"nickname":"赵老师",
"stream":"km1fvuo3",
"status":"Y",
"createdTime":1615259640000,
"lastModified":1615259640000,
"channelSessionId":null,
"sort":7,
"avatar":"//s1.videocc.net/default-img/avatar/assistant.png",
"actor":"助教",
"pageTurnEnabled":"N",
"notifyEnabled":"Y",
"checkinEnabled":"Y",
"voteEnabled":"Y",
"lotteryEnabled":"Y",
"role":"Assistant",
"chatListEnabled":"Y",
"chatAuditEnabled":"N",
"monitorEnabled":"N",
"roundTourEnabled":"N",
"watchLockEnabled":"N"
}
}
```
异常示例
```json
{
"code": 400,
"status": "error",
"message": "invalid signature.",
"data": ""
}
```