# 云端截图 (/zh-CN/realtime-media/cloud-recording/build/recording-modes/snapshot)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
单流录制模式下,你可以使用声网云端录制进行视频截图,即云端截图。
本文介绍使用云端录制 RESTful API 进行视频截图的重点步骤。建议你同时参考[云端录制快速开始](/zh-CN/realtime-media/cloud-recording/get-started/quick-start)了解云端录制的基础流程。
## 功能描述 [#功能描述]
云端录制支持对频道内的视频流进行截图,并将图片上传至你的第三方云存储。
支持以下两种截图方式:
- 在一个单流录制进程中仅截图。产生[截图费用](/zh-CN/realtime-media/cloud-recording/reference/billing-strategy/snapshot-billing)。
- 在一个单流录制进程中同时进行录制和截图。仅产生[单流录制费用](/zh-CN/realtime-media/cloud-recording/reference/billing-strategy/billing)。
:::info[信息]
如果你只需截图而无需保存录制文件,声网建议你使用性价比更高的[本地截图上传](/zh-CN/realtime-media/rtc/build/video/content-inspect)。
:::
## 前提条件 [#前提条件]
开始前,请参考[使用 RESTful API 开始云端录制](/zh-CN/realtime-media/cloud-recording/get-started/quick-start)进行一次完整的录制流程体验。
## 实现步骤 [#实现步骤]
### 1. 申请录制服务器资源 [#1-申请录制服务器资源]
开始录制前,调用 [`acquire`](/zh-CN/api-reference/api-ref/cloud-recording/acquire) 方法请求一个用于云端录制的服务器资源,并将 `clientRequest.scene` 设置为 `0`。
请求示例如下:
- 请求 URL:
```text
https://api.sd-rtn.com/v1/apps/{yourappid}/cloud_recording/acquire
```
- 请求 Body 内容:
```json
{
"cname": "httpClient463224",
"uid": "527841",
"clientRequest": {
"resourceExpiredHour": 24,
// [!code highlight:1]
"scene": 0
}
}
```
### 2. 开始截图 [#2-开始截图]
在调用 [`start`](/zh-CN/api-reference/api-ref/cloud-recording/start) 方法时,你需要将路径参数 `mode` 设为 `raw`。仅截图或同时进行录制和截图时均使用该模式。
云端截图需要设置的 `clientRequest` 字段还包括:
| 字段 | 配置内容 | 是否选填 |
| --- | --- | --- |
| `token` | 录制频道的 Token。 | 如果加入的 RTC 频道使用了 Token,则为必填。 |
| `recordingConfig` | 用于设置媒体流的订阅、转码、输出音视频的属性。 | 必填 |
| `snapshotConfig` | [snapshot-html-0-3-1 details](#table-slot-snapshot-html-0-3-1) | 必填 |
| `storageConfig` | 设置第三方云存储。 | 必填 |
| `recordingFileConfig` | 录制文件的设置。 | 如果在一个录制进程中同时进行录制和截图,则该字段为必填;如果在一个录制进程中仅截图,则不可填写该字段。 |
**snapshot-html-0-3-1 details**
设置截图周期和截图文件格式。`snapshotConfig` 包含如下字段:
- `captureInterval`:选填,表示截图周期。Number 类型,单位为秒,云端录制会按此周期定期截图。取值范围是 [1,3600],默认值为 `10`。截图仅在视频关键帧时生成,实际截图间隔可能大于设置的周期。
- `fileType`:由多个字符串组成的数组,指定截图的文件格式。目前只支持 `["jpg"]`,即生成 JPG 截图文件。
仅截图
录制并截图
仅截图时,请求 Body 示例如下:
```json
{
"uid": "527841",
"cname": "httpClient463224",
"clientRequest": {
"token": "",
"recordingConfig": {
"channelType": 1,
"subscribeUidGroup": 0
},
"snapshotConfig": {
"captureInterval": 5,
"fileType": [
"jpg"
]
},
"storageConfig": {
"accessKey": "xxxxxxf",
"region": 3,
"bucket": "xxxxx",
"secretKey": "xxxxx",
"vendor": 2,
"fileNamePrefix": [
"directory1",
"directory2"
]
}
}
}
```
录制并截图时,请求 Body 示例如下:
```json
{
"uid": "527841",
"cname": "httpClient463224",
"clientRequest": {
"token": "",
"recordingConfig": {
"maxIdleTime": 30,
"streamTypes": 1,
"channelType": 0
},
"snapshotConfig": {
"captureInterval": 5,
"fileType": [
"jpg"
]
},
// [!code highlight:5]
"recordingFileConfig": {
"avFileType": [
"hls"
]
},
"storageConfig": {
"accessKey": "xxxxxxf",
"region": 3,
"bucket": "xxxxx",
"secretKey": "xxxxx",
"vendor": 2,
"fileNamePrefix": [
"directory1",
"directory2"
]
}
}
}
```
## 截图生成文件 [#截图生成文件]
云端录制生成的截图文件的命名规则为 `___uid_s___uid_e_video_.jpg`。文件类型取决于你在 `start` 方法中设置的 `fileType`,目前只支持 JPG。
上述文件名中各字段含义如下:
- ``:录制 ID
- ``:频道名
- ``:用户 ID
- ``:该截图文件生成时的 UTC 时间,时区为 UTC + 0,由年、月、日、小时、分钟、秒和毫秒组成。例如,`utc` 为 `20190611073246073`,表示该截图文件生成时间为 UTC 2019 年 6 月 11 日 7 点 32 分 46 秒 73 毫秒。
当出现[服务器断网、进程被杀](/zh-CN/reference/faq/integration/high_availability)时,云端录制会自动启用高可用机制,在 90 秒内切换到新的服务器,自动恢复截图服务。启用高可用机制后,截图文件的文件名会增加 `bak` 前缀,`n` 为高可用机制在该次截图进程中的启用序号,`0` 表示第一次启用。以文件名 `bak0_sid_channel1__uid_s_123__uid_e_video_20190611073246073.jpg` 为例,`bak0` 表示该文件为本次截图中第一次启用高可用机制后生成的截图文件。
## 开发注意事项 [#开发注意事项]
在进行云端截图时,需要注意以下字段的设置。如设置错误,会收到报错,导致截图失败。
- 请求 URL 中的 `mode` 参数必须设为 `raw`。
- `streamTypes` 必须设置为 `1` 或 `2`。
- 如果设置了 `subscribeAudioUid`,则必须同时设置 `subscribeVideoUids`。
如果录制服务或录制上传服务异常,也会导致截图失败。
另外,在截图过程中,如果有用户中途停止发布视频流,云端录制会停止对其截图。如果你开通了[消息通知服务](/zh-CN/realtime-media/cloud-recording/build/monitor-events/enable-ncs),还会收到相应的事件回调。当该用户再次发布视频流时,云端录制会恢复对其截图。其他用户的截图不受影响。
## API 参考 [#api-参考]
你可以参考 [`acquire`](/zh-CN/api-reference/api-ref/cloud-recording/acquire) 和 [`start`](/zh-CN/api-reference/api-ref/cloud-recording/start) 方法了解字段详情。