# 快速开始云端录制 (/zh-CN/realtime-media/cloud-recording/get-started/quick-start/restful-api)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
选择你要使用的接口或 SDK,完成云端录制的环境准备、参数配置、示例运行和核心流程验证。
本文向新手介绍如何使用声网 RESTful API 开始第一次云端录制。
## 前提条件 [#前提条件]
### 开通服务并获取关键参数 [#开通服务并获取关键参数]
参考[开通云端录制服务](/zh-CN/realtime-media/cloud-recording/build/setup-and-access/enable-service)在声网控制台开通云端录制,并复制保存如下参数,以供后续使用:
- App ID
- 临时 Token
- 客户 ID
- 客户密钥
### 开通第三方云存储 [#开通第三方云存储]
云端录制文件需要上传到第三方云存储。开始录制前,请开通第三方云存储服务,并获取如下字段以备后用:
- Bucket
- Access Key
- Secret Key
开通方式请参考云存储官网文档,本文后续步骤以阿里云为例:
- [Amazon S3](https://aws.amazon.com/cn/s3/?c=s&sec=srv)
- [阿里云](https://www.aliyun.com/product/oss)
- [腾讯云](https://cloud.tencent.com/product/cos)
- [Microsoft Azure](https://azure.microsoft.com/zh-cn/services/storage/blobs/)
- [谷歌云](https://cloud.google.com/storage)
- [华为云](https://www.huaweicloud.com/product/obs.html)
- [百度智能云](https://cloud.baidu.com/product/bos.html)
### 模拟音视频互动场景 [#模拟音视频互动场景]
模拟一个音视频互动场景,云端录制服务后续会录制该场景下的音视频。
此处使用声网实时互动 [Web Demo](https://webdemo.agora.io/index.html) 在浏览器中模拟一个**基础视频直播**场景,频道内有一名主播发流:
1. 打开 Web Demo,完成**初始化设置**。
2. 进入**基础视频直播**页面,在 **Channel** 填入频道名为 show,点击 **Join as host**。
如果模拟成功,你会在 **local stream** 区域看到你的视频画面。
## 进行云端录制 [#进行云端录制]
本节介绍进行云端录制的极简流程。为方便说明,本节以录制之前模拟的音视频直播为例,并假设录制主播的音频和视频录制到 MP4 文件中。
### 申请录制服务器资源 [#申请录制服务器资源]
#### 请求 [#请求]
```bash
# [!code highlight:1]
curl --location --request POST 'https://api.sd-rtn.com/v1/apps//cloud_recording/acquire' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
# [!code highlight:1]
--header 'Authorization: ' \
--data '{
"cname": "show",
"uid": "123",
"clientRequest": {}
}'
```
你可以使用[第三方在线工具](https://www.debugbear.com/basic-auth-header-generator)快速得到 Authorization 值。将客户 ID 和客户密钥分别填入 Username 和 Password 框,得到形如 `Authorization: Basic NDI1OTQ3N2I4MzYy...YwZjA=` 的结果。将该结果替代上述代码中的 `Authorization: ` 即可。
#### 响应 [#响应]
```json
{
"cname": "show",
"uid": "123",
// [!code highlight:1]
"resourceId": "SGXETXXX"
}
```
你需要复制 `resourceId` 以备后用。
### 开始录制 [#开始录制]
#### 请求 [#请求-1]
```bash
# [!code highlight:1]
curl --location --request POST 'https://api.sd-rtn.com/v1/apps//cloud_recording/resourceid//mode/mix/start' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
# [!code highlight:1]
--header 'Authorization: ' \
--data '{
"cname": "show",
"uid": "123",
"clientRequest": {
# [!code highlight:1]
"token": "",
"recordingConfig": {
"channelType": 1
},
# [!code highlight:10]
"storageConfig": {
"vendor": 2,
"region": 3,
"bucket": "",
"accessKey": "",
"secretKey": "",
"fileNamePrefix": [
"quickstart"
]
}
}
}'
```
`"vendor": 2` 代表使用阿里云,如果你使用其他云存储厂商,请参考下表赋值:
|云存储厂商 |Vendor ID|
|-----|---|
|Amazon S3|1|
|阿里云|2|
|腾讯云|3|
|Microsoft Azure|5|
|谷歌云|6|
|华为云|7|
|百度智能云|8|
#### 响应 [#响应-1]
```json
{
"cname": "show",
"uid": "123",
"resourceId": "SGXETXXX",
// [!code highlight:1]
"sid": "04a85XXX"
}
```
你需要复制 `sid` 以备后用。
## 查看录制文件 [#查看录制文件]
参考第三方云存储官方文档操作,查看云存储中的文件。录制文件位于 `quickstart` 目录下。如下截图以阿里云为例:

在录制过程中,会有一个 `.m3u8` 和多个 `.ts` 文件。点击任意一个 `.ts` 文件即可播放。
如果还需要查看 `.mp4` 文件,你需要先结束录制,再查看云存储文件。结束录制可参照如下代码:
```bash
# [!code highlight:1]
curl --location --request POST 'https://api.sd-rtn.com/v1/apps//cloud_recording/resourceid//sid//mode/mix/stop' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
# [!code highlight:1]
--header 'Authorization: ' \
--data '{
"cname": "show",
"uid": "123",
"clientRequest": {}
}'
```
最终 `quickstart` 录制文件夹内包含如下:
```shell
.
├── _show.m3u8
├── _show_0.mp4
├── _show_20240507070329192.ts
├── _show_20240507070346226.ts
├── _show_20240507070402264.ts
├── _show_20240507070418236.ts
├── _show_20240507070434208.ts
├── _show_20240507070450246.ts
├── _show_20240507070506218.ts
├── _show_20240507070522256.ts
├── _show_20240507070538236.ts
├── _show_20240507070554266.ts
├── _show_20240507070610238.ts
├── _show_20240507070626210.ts
└── _show_20240507070642248.ts
```
有关录制文件的详细信息,请参考[录制文件介绍](/zh-CN/realtime-media/cloud-recording/build/manage-recorded-files/introduce-recorded-files)。
## 进阶设置 [#进阶设置]
本文提供的示例代码仅为快速上手时使用。在实际业务中,你需要根据实际业务场景修改请求参数。如下示例代码展示了录制直播频道中所有的音视频流,且输出的视频流需要转码的参数配置:
```bash
curl --location --request POST 'https://api.sd-rtn.com/v1/apps//cloud_recording/resourceid//mode/mix/start' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: ' \
--data '{
"cname": "show",
"uid": "123",
"clientRequest": {
"token": "",
# [!code highlight:20]
"recordingConfig": {
"channelType": 1,
"streamTypes": 2,
"audioProfile": 2,
"maxIdleTime": 30,
"transcodingConfig": {
"width": 640,
"height": 640,
"fps": 15,
"bitrate": 800,
"mixedVideoLayout": 0,
"backgroundColor": "#000000"
},
"subscribeVideoUids": [
"#allstream#"
],
"subscribeAudioUids": [
"#allstream#"
]
},
"recordingFileConfig": {
"avFileType": [
"hls",
"mp4"
]
},
"storageConfig": {
"vendor": 2,
"region": 3,
"bucket": "",
"accessKey": "",
"secretKey": "",
"fileNamePrefix": [
"quickstart"
]
}
}
}'
```
云端录制支持设置的所有参数请参考 [API 文档](/zh-CN/api-reference/api-ref/cloud-recording/start)。
## 排查错误 [#排查错误]
- [响应状态码和错误码](/zh-CN/realtime-media/cloud-recording/reference/response-code)
- [为什么成功开启云端录制后调用 query 方法返回 404?](/zh-CN/reference/faq/integration/return_404)
- [应用崩溃后对云端录制有什么影响?](/zh-CN/reference/faq/integration/abnormal_exit)
- [如何选择云存储 bucket 区域及处理跨区上传问题?](/zh-CN/reference/faq/integration/bucket_region)
- [为什么无法通过浏览器调用云端录制 RESTful API?](/zh-CN/reference/faq/product/call_api_in_browser)
- [为什么第三方云存储中没有录制文件?](/zh-CN/reference/faq/integration/fail_to_upload)
- [如何获取 M3U8 文件地址?](/zh-CN/reference/faq/integration/acquire_file_directory)
- [云端录制如何处理服务器断网、进程被杀问题?](/zh-CN/reference/faq/integration/high_availability)