开始云端录制
更新时间不可用
开始一个云端录制任务。
https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/mode/{mode}/startstart 方法用于开始云端录制。
通过 acquire 方法获取云端录制资源后，调用 start 方法开始云端录制。
注意
发起 start 请求后，你还需要依据保障录制成功启动检查录制服务是否已经成功启动。
appidstring你的项目使用的 App ID。
- 对于页面录制模式，只需输入开通了云端录制服务的 App ID。
- 对于单流和合流录制模式，必须使用和待录制的频道相同的 App ID，且该 App ID 需要开通云端录制服务。
resourceidstring通过 acquire 请求获取到的 Resource ID。
Authorizationstring声网云端录制 RESTful API 仅支持 HTTPS 协议。发送请求时，你需要使用声网提供的客户 ID 和客户密钥生成 Base64 编码凭证，并填入请求头部的 Authorization 字段中。详见实现 HTTP 基本认证。
Content-Typestringapplication/json。
cnamestring录制服务所在频道的名称。需要和你在 acquire 请求中输入的 cname 相同。
uidstring字符串内容为录制服务在 RTC 频道内使用的 UID，用于标识该录制服务，需要和你在 acquire 请求中输入的 uid 相同。
设置该字段后，可以提升可用性并优化负载均衡。
注意
如果填写该字段，则必须确保 startParameter object 和后续 start 请求中填写的 clientRequest object 完全一致，且取值合法，否则 start 请求会收到报错。
tokenstring用于鉴权的动态密钥（Token）。如果你的项目已启用 App 证书，则务必在该字段中传入你项目的动态密钥。详见使用 Token 鉴权。
注意：
- 仅需在单流录制和合流录制模式下设置。
- 云端录制服务暂不支持更新 Token。为保证录制正常，请确保 Token 有效时长大于你预计的录制时长，以避免 Token 过期导致录制任务退出频道而结束录制。
第三方云存储的配置项。
regionnumber第三方云存储指定的地区信息。
注意
为确保录制文件上传的成功率和实时性，第三方云存储的 region 与你发起请求的应用服务器必须在同一个区域中。例如：你发起请求的 App 服务器在中国大陆地区，则第三方云存储需要设置为中国大陆区域内。详见第三方存储地区说明。
bucketstring第三方云存储的 Bucket。Bucket 名称需要符合对应第三方云存储服务的命名规则。
accessKeystring第三方云存储的 Access Key（访问密钥）。
secretKeystring第三方云存储的 Secret Key。
stsTokenstring第三方云存储的临时安全令牌。该令牌由云服务商的安全令牌服务 (Security Token Service, STS) 临时颁发，用于授予第三方云存储资源的有限访问权限。
说明
- 目前支持的云服务商仅包括，
1：Amazon S3，2：阿里云，3：腾讯云。
stsExpirationnumber用于标记 stsToken 的过期时间戳，POSIX 时间，单位为秒。
注意
- 为避免时间戳溢出问题，建议使用 Uint64 存储。
- 建议在申请
stsToken时设置尽可能长的有效期，最短有效期需不少于 4 小时，并需要在过期前调用update方法更新stsToken的值 - 如录制任务持续时间超过 1 小时，需每 60 分钟重新申请
stsToken，并调用update更新storageConfig中的相关参数。
fileNamePrefixarray<string>录制文件在第三方云存储中的存储位置，与录制文件名前缀有关。如果设为 ["directory1","directory2"]，那么录制文件名前缀为 "directory1/directory2/"，即录制文件名为 directory1/directory2/xxx.m3u8。前缀长度（包括斜杠）不得超过 128 个字符。字符串中不得出现斜杠、下划线、括号等符号字符。以下为支持的字符集范围：
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0-9
第三方云存储服务会按照该字段设置对已上传的录制文件进行加密和打标签。
ssestring加密模式。设置该字段后，第三方云存储服务会按照该加密模式将已上传的录制文件进行加密。该字段仅适用于 Amazon S3，详见 Amazon S3 官方文档。
kms：KMS 加密。aes256：AES256 加密。
tagstring标签内容。设置该字段后，第三方云存储服务会按照该标签内容将已上传的录制文件进行打标签操作。该字段仅适用于阿里云和 Amazon S3，详见阿里云官方文档和 Amazon S3 官方文档。
endpointstringS3 协议云存储的域名。当 vendor 设为 11 时，该字段为必填。
录制的音视频流配置项。
注意：仅需在单流录制和合流录制模式下设置。
channelTypenumber频道场景。
0：通信场景。1：直播场景。
注意
频道场景必须与声网 RTC SDK 的设置一致，否则可能导致问题。
decryptionModenumber解密模式。如果你在 SDK 客户端设置了频道加密，那么你需要对云端录制服务设置与加密相同的解密模式。
0：不加密。1：AES_128_XTS 加密模式。128 位 AES 加密，XTS 模式。2：AES_128_ECB 加密模式。128 位 AES 加密，ECB 模式。3：AES_256_XTS 加密模式。256 位 AES 加密，XTS 模式。4：SM4_128_ECB 加密模式。128 位 SM4 加密，ECB 模式。5：AES_128_GCM 加密模式。128 位 AES 加密，GCM 模式。6：AES_256_GCM 加密模式。256 位 AES 加密，GCM 模式。7：AES_128_GCM2 加密模式。128 位 AES 加密，GCM 模式。相比于 AES_128_GCM 加密模式，AES_128_GCM2 加密模式安全性更高且需要设置密钥和盐。8：AES_256_GCM2 加密模式。256 位 AES 加密，GCM 模式。相比于 AES_256_GCM 加密模式，AES_256_GCM2 加密模式安全性更高且需要设置密钥和盐。
secretstring与加解密相关的密钥。仅需在 decryptionMode 非 0 时设置。
saltstring与加解密相关的盐。Base64 编码、32 位字节。仅需在 decryptionMode 为 7 或 8 时设置。
maxIdleTimenumber最大频道空闲时间。单位为秒。最大值不超过 30 天。超出最大频道空闲时间后，录制服务会自动退出。录制服务退出后，如果你再次发起 start 请求，会产生新的录制文件。
频道空闲：直播频道内无任何主播，或通信频道内无任何用户。
streamTypesnumber订阅的媒体流类型。
0：仅订阅音频。适用于智能语音审核场景。1：仅订阅视频。2：订阅音频和视频。
videoStreamTypenumber设置订阅的视频流类型。如果你在 SDK 客户端开启了双流模式，你可以选择订阅视频大流或者小流。
0：视频大流，即高分辨率高码率的视频流1：视频小流，即低分辨率低码率的视频流
subscribeAudioUidsarray<string>指定订阅哪几个 UID 的音频流。如需订阅全部 UID 的音频流，则无需设置该字段。数组长度不得超过 32，不推荐使用空数组。该字段和 unSubscribeAudioUids 只能设一个。详见设置订阅名单。
注意：
- 该字段仅适用于 streamTypes 设为音频，或音频和视频的情况。
- 如果你设置了音频的订阅名单，但没有设置视频的订阅名单，云端录制服务不会订阅任何视频流。反之亦然。
- 设为 ["#allstream#"] 可订阅频道内所有 UID 的音频流。
unSubscribeAudioUidsarray<string>指定不订阅哪几个 UID 的音频流。云端录制会订阅频道内除指定 UID 外所有 UID 的音频流。数组长度不得超过 32，不推荐使用空数组。该字段和 subscribeAudioUids 只能设一个。详见设置订阅名单。
subscribeVideoUidsarray<string>指定订阅哪几个 UID 的视频流。如需订阅全部 UID 的视频流，则无需设置该字段。数组长度不得超过 32，不推荐使用空数组。该字段和 unSubscribeVideoUids 只能设一个。详见设置订阅名单。
注意：
- 该字段仅适用于 streamTypes 设为视频，或音频和视频的情况。
- 如果你设置了视频的订阅名单，但没有设置音频的订阅名单，云端录制服务不会订阅任何音频流。反之亦然。
- 设为 ["#allstream#"] 可订阅频道内所有 UID 的视频流。
unSubscribeVideoUidsarray<string>指定不订阅哪几个 UID 的视频流。云端录制会订阅频道内除指定 UID 外所有 UID 的视频流。数组长度不得超过 32，不推荐使用空数组。该字段和 subscribeVideoUids 只能设一个。详见设置订阅名单。
subscribeUidGroupnumber预估的订阅人数峰值。
0：1 到 2 个 UID。1：3 到 7 个 UID。2：8 到 12 个 UID。3：13 到 17 个 UID。4：18 到 32 个 UID。5：33 到 49 个 UID。
注意
- 仅需在单流录制模式下设置，且单流录制模式下必填。
- 举例来说，如果
subscribeVideoUids为["100","101","102"]，subscribeAudioUids为["101","102","103"]，则订阅人数为 4 人。
audioProfilenumber设置输出音频的采样率、码率、编码模式和声道数。
0：48 kHz 采样率，音乐编码，单声道，编码码率约 48 Kbps。1：48 kHz 采样率，音乐编码，单声道，编码码率约 128 Kbps。2：48 kHz 采样率，音乐编码，双声道，编码码率约 192 Kbps。
说明
仅需在合流录制模式下设置。
转码输出的视频配置项。取值可参考设置录制输出视频的分辨率。
注意：仅需在合流录制模式下设置。
widthnumber视频的宽度，单位为像素。width 和 height 的乘积不能超过 1920 × 1080。
heightnumber视频的高度，单位为像素。width 和 height 的乘积不能超过 1920 × 1080。
fpsnumber视频的帧率，单位 fps。
bitratenumber视频的码率，单位 Kbps。
maxResolutionUidstring仅需在垂直布局下设置。指定显示大视窗画面的用户 UID。字符串内容的整型取值范围 1 到 (232-1)，且不可设置为 0。
mixedVideoLayoutnumber视频合流布局：
0：悬浮布局。第一个加入频道的用户在屏幕上会显示为大视窗，铺满整个画布，其他用户的视频画面会显示为小视窗，从下到上水平排列，最多 4 行，每行 4 个画面，最多支持共 17 个画面。1：自适应布局。根据用户的数量自动调整每个画面的大小，每个用户的画面大小一致，最多支持 17 个画面。2：垂直布局。指定maxResolutionUid在屏幕左侧显示大视窗画面，其他用户的小视窗画面在右侧垂直排列，最多两列，一列 8 个画面，最多支持共 17 个画面。3：自定义布局。由你在layoutConfig字段中自定义合流布局。
backgroundColorstring视频画布的背景颜色。支持 RGB 颜色表，字符串格式为 # 号和 6 个十六进制数。默认值 "#000000"，代表黑色。
backgroundImagestring视频画布的背景图的 URL。背景图的显示模式为裁剪模式。
裁剪模式：优先保证画面被填满。背景图尺寸等比缩放，直至整个画面被背景图填满。如果背景图长宽与显示窗口不同，则背景图会按照画面设置的比例进行周边裁剪后填满画面。
defaultUserBackgroundImagestring默认的用户画面背景图的 URL。
配置该字段后，当任一⽤户停止发送视频流超过 3.5 秒，画⾯将切换为该背景图；如果针对某 UID 单独设置了背景图，则该设置会被覆盖。
用户的合流画面布局。由每个用户对应的布局画面设置组成的数组，支持最多 17 个用户。
注意：仅需在自定义布局下设置。
uidstring字符串内容为待显示在该区域的用户的 UID，32 位无符号整数。
如果不指定 UID，会按照用户加入频道的顺序自动匹配 layoutConfig 中的画面设置。
x_axisnumber屏幕里该画面左上角的横坐标的相对值，精确到小数点后六位。从左到右布局，0.0 在最左端，1.0 在最右端。该字段也可以设置为整数 0 或 1。
y_axisnumber屏幕里该画面左上角的纵坐标的相对值，精确到小数点后六位。从上到下布局，0.0 在最上端，1.0 在最下端。该字段也可以设置为整数 0 或 1。
widthnumber该画面宽度的相对值，精确到小数点后六位。该字段也可以设置为整数 0 或 1。
heightnumber该画面高度的相对值，精确到小数点后六位。该字段也可以设置为整数 0 或 1。
alphanumber图像的透明度。精确到小数点后六位。0.0 表示图像为透明的，1.0 表示图像为完全不透明的。
render_modenumber画面显示模式：
0：裁剪模式。优先保证画面被填满。视频尺寸等比缩放，直至整个画面被视频填满。如果视频长宽与显示窗口不同，则视频流会按照画面设置的比例进行周边裁剪后填满画面。1：缩放模式。优先保证视频内容全部显示。视频尺寸等比缩放，直至视频窗口的一边与画面边框对齐。如果视频尺寸与画面尺寸不一致，在保持长宽比的前提下，将视频进行缩放后填满画面，缩放后的视频四周会有一圈黑边。
用户的背景图设置。
uidstring字符串内容为用户 UID。
image_urlstring该用户的背景图 URL。配置背景图后，当该⽤户停止发送视频流超过 3.5 秒，画⾯将切换为该背景图。
URL 支持 HTTP 和 HTTPS 协议，图片格式支持 JPG 和 BMP。图片大小不得超过 6 MB。录制服务成功下载图片后，设置才会生效；如果下载失败，则设置不⽣效。不同字段设置可能会互相覆盖，具体规则详见设置背景色或背景图。
render_modenumber画面显示模式：
0：裁剪模式。优先保证画面被填满。视频尺寸等比缩放，直至整个画面被视频填满。如果视频长宽与显示窗口不同，则视频流会按照画面设置的比例进行周边裁剪后填满画面。1：缩放模式。优先保证视频内容全部显示。视频尺寸等比缩放，直至视频窗口的一边与画面边框对齐。如果视频尺寸与画面尺寸不一致，在保持长宽比的前提下，将视频进行缩放后填满画面，缩放后的视频四周会有一圈黑边。
录制文件配置项。
注意：仅截图时不可设置该字段，其他情况都需要设置该字段。其他情况包含如下：
- 单流录制模式下，不转码录制，转码录制，或同时录制和截图。
- 合流录制。
- 页面录制模式下，仅页面录制，或同时页面录制和转推到 CDN。
avFileTypearray<string>录制生成的文件类型：
"hls"：HLS 格式的 M3U8 和 TS 文件。单流录制时，音频和视频输出到同一个 M3U8 文件。"mp4"：MP4 文件。"mp3"：MP3 文件，仅适用于单流录制且仅录制音频的场景。
注意
- 单流录制模式下，且非仅截图情况，默认输出 HLS 文件；如果需要生成 MP4 文件，需将
avFileType设置为["hls","mp4"]。 - 单流录制且仅录制音频时，将
avFileType设置为["hls","mp3"]可直接输出 MP3 文件。 - 合流录制和页面录制模式下，如果你需要生成 MP4 文件，那么设为
["hls","mp4"]。仅设为["mp4"]会收到报错。设置后，录制文件行为如下：- 合流录制模式：录制服务会在当前 MP4 文件时长超过约 3 小时或文件大小超过约 2 GB 左右时，创建一个新的 MP4 文件。
- 页面录制模式：录制服务会在当前 MP4 文件时长超过
maxVideoDuration（默认 180 分钟）或文件大小超过约 2 GB 时，创建一个新的 MP4 文件。
云端截图配置项。
注意：仅需在单流录制模式下，且使用截图功能时设置。
截图使用须知：- 截图功能仅适用于单流录制模式（
raw）。 - 你可以在一个单流录制进程中仅截图，或同时录制和截图，详见云端截图。同时录制和截图的情况需要设置
recordingFileConfig字段。 - 如果录制服务或录制上传服务异常，则截图失败。截图异常时，录制不受影响。
- 使用截图时，
streamTypes必须设置为 1 或 2。如果设置了subscribeAudioUid，则必须同时设置subscribeVideoUids。
captureIntervalnumber云端录制定期截图的截图周期。单位为秒。截图仅在视频关键帧时生成，实际截图间隔可能大于设置的周期。
fileTypearray<string>截图的文件格式。目前只支持 ["jpg"]，即生成 JPG 格式的截图文件。
扩展服务配置项。
注意：仅需在页面录制模式下设置。
errorHandlePolicystring错误处理策略。默认且仅可设为 "error_abort"，表示当扩展服务发生错误后，订阅和云端录制的其他非扩展服务都停止。
serviceNamestring扩展服务的名称：
web_recorder_service：代表扩展服务为页面录制。rtmp_publish_service：代表扩展服务为转推页面录制到 CDN。
errorHandlePolicystring扩展服务内的错误处理策略：
"error_abort"：页面录制时默认且只能为该值。表示当前扩展服务出错时，停止其他扩展服务。"error_ignore"：转推页面录制到 CDN 时默认且只能为该值。表示当前扩展服务出错时，其他扩展服务不受影响。
如果页面录制服务或录制上传服务异常，那么推流到 CDN 失败，因此页面录制服务出错会影响转推页面录制到 CDN 服务。
转推到 CDN 的过程发生异常时，页面录制不受影响。
扩展服务的具体配置项。
页面录制时需设置如下字段。
urlstring待录制页面的地址。
audioProfilenumber输出音频的采样率、码率、编码模式和声道数。
0：48 kHz 采样率，音乐编码，单声道，编码码率约 48 Kbps。1：48 kHz 采样率，音乐编码，单声道，编码码率约 128 Kbps。2：48 kHz 采样率，音乐编码，双声道，编码码率约 192 Kbps。
videoWidthnumber输出视频的宽度，单位为 pixel。videoWidth 和 videoHeight 的乘积需小于等于 1920 × 1080。推荐值可参考如何设置页面录制移动端网页模式的输出视频分辨率。
videoHeightnumber输出视频的高度，单位为 pixel。videoWidth 和 videoHeight 的乘积需小于等于 1920 × 1080。推荐值可参考如何设置页面录制移动端网页模式的输出视频分辨率。
maxRecordingHournumber页面录制的最大时长，单位为小时。超出该值后页面录制会自动停止。
建议
建议取值不超过你在 acquire 方法中设置的 resourceExpiredHour 的值。
计费相关：页面录制停止前会持续计费，因此请根据实际业务情况设置合理的值或主动停止页面录制。
videoBitratenumber输出视频的码率，单位为 Kbps。针对不同的输出视频分辨率，videoBitrate 的默认值不同：
- 输出视频分辨率大于或等于 1280 × 720：默认值为 2000。
- 输出视频分辨率小于 1280 × 720：默认值为 1500。
videoFpsnumber输出视频的帧率，单位为 fps。
mobileboolean是否开启移动端网页模式：
true：开启。开启后，录制服务使用移动端网页渲染模式录制当前页面。false：（默认）不开启。
maxVideoDurationnumber页面录制生成的 MP4 切片文件的最大时长，单位为分钟。页面录制过程中，录制服务会在当前 MP4 文件时长超过约 maxVideoDuration 左右时创建一个新的 MP4 切片文件。
onholdboolean是否在启动页面录制任务时暂停页面录制。
true：在启动页面录制任务时暂停页面录制。开启页面录制任务后立即暂停录制，录制服务会打开并渲染待录制页面，但不生成切片文件。false：启动页面录制任务并进行页面录制。
建议你按照如下流程使用 onhold 字段：
- 调用
start方法时将onhold设为true，开启并暂停页面录制，自行判断页面录制开始的合适时机。 - 调用
update并将onhold设为false，继续进行页面录制。如果需要连续调用update方法暂停或继续页面录制，请在收到上一次update响应后再进行调用，否则可能导致请求结果与预期不一致。
readyTimeoutnumber设置页面加载超时时间，单位为秒。详见页面加载超时检测。
0或不设置，表示不检测页面加载状态。- [1,60] 之间的整数，表示页面加载超时时间。
转推页面录制到 CDN 时需设置如下字段。
rtmpUrlstringCDN 推流地址。
响应
如果返回的 HTTP 状态码为 200，表示请求成功。
如需检查录制服务是否已经成功启动，请参考监控录制状态操作。
响应 Body
cnamestring录制的频道名。
uidstring字符串内容为云端录制服务在 RTC 频道内使用的 UID，用于标识频道内的录制服务。
resourceIdstring云端录制资源 Resource ID。使用这个 Resource ID 可以开始一段云端录制。这个 Resource ID 的有效期为 5 分钟，超时需要重新请求。
sidstring录制 ID。成功开始云端录制后，你会得到一个 Sid （录制 ID）。该 ID 是一次录制周期的唯一标识。
请求示例
curl --request POST \
--url "https://api.sd-rtn.com/v1/apps/:appid/cloud_recording/resourceid/:resourceid/mode/:mode/start" \
--header 'Authorization: Basic <credentials>' \
-H 'Content-Type: application/json' \
-d '{
"cname": "<your_channel_name>",
"uid": "<unique_user_id>",
"clientRequest": {
"token": "<your_token>",
"recordingConfig": {
"channelType": 1,
"streamTypes": 2,
"videoStreamType": 0,
"maxIdleTime": 30,
"subscribeAudioUids": [
"#allstream#"
],
"subscribeVideoUids": [
"#allstream#"
],
"subscribeUidGroup": 5
},
"recordingFileConfig": {
"avFileType": [
"hls",
"mp4"
]
},
"storageConfig": {
"vendor": 2,
"region": 3,
"bucket": "<your_storage_bucket>",
"accessKey": "<your_storage_access_key>",
"secretKey": "<your_storage_secret_key>",
"fileNamePrefix": [
"quickstart"
],
"extensionParams": {
"tag": "RETENTION_DAYS=30"
}
}
}
}'响应示例
{
"cname": "录制的频道名。",
"uid": "字符串内容为云端录制服务在 RTC 频道内使用的 UID，用于标识频道内的录制服务。",
"resourceId": "云端录制资源 Resource ID。使用这个 Resource ID 可以开始一段云端录制。这个 Resource ID 的有效期为 5 分钟，超时需要重新请求。",
"sid": "录制 ID。成功开始云端录制后，你会得到一个 Sid （录制 ID）。该 ID 是一次录制周期的唯一标识。"
}