# 云端截图 (/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) 方法了解字段详情。