# 云端截图 (/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` 设为 `individual`。

云端截图需要设置的 `clientRequest` 字段还包括：

| 字段 | 配置内容 | 是否选填 |
| --- | --- | --- |
| `token` | 录制频道的 Token。 | 如果加入的 RTC 频道使用了 Token，则为必填。 |
| `recordingConfig` | 用于设置媒体流的订阅、转码、输出音视频的属性。 | 必填 |
| `snapshotConfig` | [snapshot-html-0-3-1 details](#table-slot-snapshot-html-0-3-1) | 必填 |
| `storageConfig` | 设置第三方云存储。 | 必填 |
| `recordingFileConfig` | 录制文件的设置。 | 如果在一个录制进程中同时进行录制和截图，则该字段为必填；如果在一个录制进程中仅截图，则不可填写该字段。 |

<a id="table-slot-snapshot-html-0-3-1"></a>

**snapshot-html-0-3-1 details**

设置截图周期和截图文件格式。`snapshotConfig` 包含如下字段：

- `captureInterval`：选填，表示截图周期。Number 类型，单位为秒，云端录制会按此周期定期截图。取值范围是 [1,3600]，默认值为 `10`。截图仅在视频关键帧时生成，实际截图间隔可能大于设置的周期。
- `fileType`：由多个字符串组成的数组，指定截图的文件格式。目前只支持 `["jpg"]`，即生成 JPG 截图文件。

<Tabs defaultValue="Snapshot only" groupId="是否同时录制和截图" persist>
<TabsList>
  <TabsTrigger value="Snapshot only">仅截图</TabsTrigger>
  <TabsTrigger value="Record and snapshot">录制并截图</TabsTrigger>
</TabsList>

<TabsContent value="Snapshot only">

仅截图时，请求 Body 示例如下：

```json
{
  "uid": "527841",
  "cname": "httpClient463224",
  "clientRequest": {
    "token": "<token if any>",
    "recordingConfig": {
      "channelType": 1,
      "subscribeUidGroup": 0
    },
    "snapshotConfig": {
      "captureInterval": 5,
      "fileType": [
        "jpg"
      ]
    },
    "storageConfig": {
      "accessKey": "xxxxxxf",
      "region": 3,
      "bucket": "xxxxx",
      "secretKey": "xxxxx",
      "vendor": 2,
      "fileNamePrefix": [
        "directory1",
        "directory2"
      ]
    }
  }
}
```

</TabsContent>

<TabsContent value="Record and snapshot">

录制并截图时，请求 Body 示例如下：

```json
{
  "uid": "527841",
  "cname": "httpClient463224",
  "clientRequest": {
    "token": "<token if any>",
    "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"
      ]
    }
  }
}
```

</TabsContent>
</Tabs>

## 截图生成文件 [#截图生成文件]

云端录制生成的截图文件的命名规则为 `<sid>_<cname>__uid_s_<uid>__uid_e_video_<utc>.jpg`。文件类型取决于你在 `start` 方法中设置的 `fileType`，目前只支持 JPG。

上述文件名中各字段含义如下：

- `<sid>`：录制 ID
- `<cname>`：频道名
- `<uid>`：用户 ID
- `<utc>`：该截图文件生成时的 UTC 时间，时区为 UTC + 0，由年、月、日、小时、分钟、秒和毫秒组成。例如，`utc` 为 `20190611073246073`，表示该截图文件生成时间为 UTC 2019 年 6 月 11 日 7 点 32 分 46 秒 73 毫秒。

当出现[服务器断网、进程被杀](/zh-CN/reference/faq/integration/high_availability)时，云端录制会自动启用高可用机制，在 90 秒内切换到新的服务器，自动恢复截图服务。启用高可用机制后，截图文件的文件名会增加 `bak<n>` 前缀，`n` 为高可用机制在该次截图进程中的启用序号，`0` 表示第一次启用。以文件名 `bak0_sid_channel1__uid_s_123__uid_e_video_20190611073246073.jpg` 为例，`bak0` 表示该文件为本次截图中第一次启用高可用机制后生成的截图文件。

## 开发注意事项 [#开发注意事项]

在进行云端截图时，需要注意以下字段的设置。如设置错误，会收到报错，导致截图失败。

- 请求 URL 中的 `mode` 参数必须设为 `individual`。
- `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) 方法了解字段详情。