创建云端录制任务
更新时间： 2025/09/17 09:14:53
调用此接口创建一个云端录制任务，支持录制音视频通话的过程，包括屏幕共享和其他自定义音视频，并生成录制文件。
功能描述
通过本接口实现云端录制时，可以设置音视频通话全局的录制相关参数，包括录制布局、录制模式、是否开启内容安全审核、是否添加水印等，相关配置对房间内所有成员生效。
-
录制布局：支持设置录制的画面布局，包括两种全新布局（悬浮和垂直布局），若此处设置的画面布局与控制台中的全应用录制布局设置冲突，以此处的设置为准。
-
录制模式：支持设置房间内所有成员的录制模式，包括单流录制、合流录制等。
同一时刻，一个音视频房间中只能创建一个云端录制任务。
-
计费方式：该功能涉及资源计费，请确认您已了解 云端录制计费说明。
接口版本
网易云信于 2021 年 11 月 18 日上线纯服务端的云端录制方案，即一套新版云端录制服务端 API，为您提供录制任务的启停、查询以及录制订阅列表的更新等功能。
- 在新版 API 提供更丰富的录制布局、支持订阅黑白名单设置、方案更加细节和灵活。
- 同一房间中，不可同时使用新旧两套云端录制 API。
旧版云端录制 API 仍会持续维护，但网易云信推荐您切换至新版云端录制 API，以体验更为灵活的云端录制配置。
接口限制
默认上限为 50 次/秒，若请求频率超出限制，可能会返回 429 错误码。若您需要上调上限，请参考 如何处理调用服务端 RESTful API 超出频率限制。
请求信息
请求 URL
- 请求方法：POST
- 请求 URL：网易云信为该功能提供以下两个 API 请求地址，使用 V3 地址需在 URL 中指定 cname，您可以根据业务需求调用任一接口。
https://rtc.yunxinapi.com/v2/api/cloudrecord/submithttps://rtc.yunxinapi.com/v3/api/cloudrecord/submit?cname={cname}
请求路径参数
URL 中参数说明：
| 参数名称 | 类型 | 示例 | 说明 |
|---|---|---|---|
| cname | String | abc | 房间名称。仅在调用 V3 接口时需要设置。 |
请求头参数
请求中 Header 的设置请参考 请求结构 描述。
请求体参数
| 参数名称 | 类型 | 是否必选 | 说明 |
|---|---|---|---|
| cid | Number | 必选，仅适用于 V2 接口 | 房间 ID。该 ID 为创建房间接口调用成功后返回的房间 ID。仅在调用 V2 接口时需要设置。 |
| recordConfig | recordConfig | 否 | 录制模式。详细信息请参考 recordConfig。 支持如下三种模式：
|
| streamSubscribe | streamSubscribe | 否 | 在录制过程中，通过黑白名单指定订阅某些用户的音频流或视频流。具体请参考 订阅名单。 默认为订阅房间内所有发布的音视频流。 |
| detect | detect | 否 | 内容安全审核配置。详细信息请参考 detect。 |
|
layoutConfig |
否 |
录制布局配置。详细信息请参考 录制布局
|
|
| watermark | watermark | 否 | 水印配置。详细信息请参考 watermark。 |
请求体示例
JSON{
"cid":11***77184,
"recordConfig": {
"recordType": 100,
"modeList": [
{
"mode": 0,
"layoutType": 2,
"layout":
{
"canvas": {
"width": 720,
"height": 480
},
"subStreams": [
{
"adaption": 0,
"x": 0,
"width": 720,
"y": 0,
"zOrder": 1,
"height": 384
}
],
"users": [
{
"adaption": 1,
"x": 270,
"width": 144,
"zOrder": 2,
"y": 384,
"height": 96
}
]
}
},
{
"mode": 1
}
]
},
"detect":{
"enableSpamDetect":true,
"scFrequency":1,
"detectType":1
},
"layoutConfig":{
"hostUid":66602,
"layoutType":3
},
"streamSubscribe":{
"streamType":2,
"audioUidList":{
"subscribeUids":[
4455,
66602
]
},
"videoUidList":{
"unSubscribeUids":[
4455
]
}
}
"watermark":{
"literaWms":[
{
"wmLitera": "水印测试",
"fontSize":50,
"fontColor":"#FF0000",
"offsetX":0,
"offsetY":0
}
],
"transparentLayers":[
{
"offsetX":0,
"offsetY":0,
"wmWidth":480,
"wmHeight":100,
"bgTransparency":3
}
],
"imgWms":[
{
"url":"https://freepngimg.com/XXX/XXX/example.png",
"offsetX":120,
"offsetY":120,
"wmWidth":100,
"wmHeight":100
}
],
"timestampWm":{
"fontSize":50,
"fontColor":"#FF0000",
"offsetX":0,
"offsetY":50
}
}
}
以上示例代码为订阅房间内部分用户的音频流和视频流，实现订阅房间内 全部 用户的音、视频流的示例代码请参考 更新订阅名单。
响应信息
响应体参数
返回结构请参考 云端录制返回结构。其中，业务相关参数封装在 record 参数中，包括：
| 参数名称 | 类型 | 示例 | 说明 |
|---|---|---|---|
| taskId | String | 1143932537695968 | 录制任务 ID，为任务唯一标识符，且房间内唯一。 |
| cid | Number | 123456 | 房间 ID。 |
响应体示例
JSON{
"code": 200,
"record": {
"taskId": "23d73e2ae2c74135a732c8d24739b71d8723",
"cid": 11443***77184
}
}
状态码
响应内容中，code 为 200 表示调用正常，若 code 为其他值，请根据 code 与 errmsg 在 云端录制相关错误码 中查看问题原因与解决方法。
