# 停止云端录制 (/zh-CN/api-reference/api-ref/cloud-recording/stop)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

停止一个云端录制任务。

- OpenAPI: /openapi/cloud-recording/cloud-recording.zh-CN.yaml
- Operation ID: stop-cloud-recording
- Method: POST
- Path: /v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/stop
- Endpoint: https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/stop

## Servers

- https://api.sd-rtn.com

`stop` 方法用于停止云端录制。

开始录制后，你可以调用 `stop` 方法离开频道，停止录制。录制停止后如需再次录制，必须再调用 `acquire` 方法请求一个新的 Resource ID。


:::warning[注意]
- `stop` 请求仅在会话内有效。如果录制启动错误，或录制已结束，调用 `stop` 将返回 `404`。
- 非页面录制模式下，当频道空闲（无用户）超过预设时间（默认为 30 秒） 后，云端录制也会自动退出频道，停止录制。
- 录制结束后，正常情况下录制文件会在 20 分钟内上传至第三方云存储，但在网络异常等特殊情况下上传时间会达到 24 小时以上。
:::

## Authorization

This endpoint requires authentication.

- `Basic Auth`

## Parameters

- `Authorization` (header, required, string) - 声网云端录制 RESTful API 仅支持 HTTPS 协议。发送请求时，你需要使用声网提供的客户 ID 和客户密钥生成 Base64 编码凭证，并填入请求头部的 `Authorization` 字段中。详见[实现 HTTP 基本认证](/zh-CN/realtime-media/cloud-recording/build/setup-and-access/http-basic-auth)。
  - Example: `Basic <credentials>`
- `Content-Type` (header, optional, string) - `application/json`。
- `appid` (path, required, string) - 你的项目使用的 [App ID](/zh-CN/realtime-media/cloud-recording/build/setup-and-access/enable-service#获取-app-id)。

- 对于页面录制模式，只需输入开通了云端录制服务的 App ID。
- 对于单流和合流录制模式，必须使用和待录制的频道相同的 App ID，且该 App ID 需要开通云端录制服务。
- `resourceid` (path, required, string) - 通过 [`acquire`](./acquire) 请求获取到的 Resource ID。
- `sid` (path, required, string) - 通过 [`start`](./start) 获取的录制 ID。
- `mode` (path, required, string) - 录制模式：

- `raw`：[单流录制模式](/zh-CN/realtime-media/cloud-recording/build/recording-modes/individual-mode/set-individual)。
- `mix`：[合流录制模式](/zh-CN/realtime-media/cloud-recording/build/recording-modes/mix-mode/set-composite)。
- `web`：[页面录制模式](/zh-CN/realtime-media/cloud-recording/build/recording-modes/web-mode/set-webpage-recording)。

## Request body

- `cname` (string, required) - 录制服务所在频道的名称。需要和你在 [`acquire`](./acquire) 请求中输入的 `cname` 相同。
- `uid` (string, required) - 字符串内容为录制服务在 RTC 频道内使用的 UID，用于标识该录制服务，需要和你在 [`acquire`](./acquire) 请求中输入的 `uid` 相同。
- `clientRequest` (object, required)
  - `clientRequest.async_stop` (boolean) - 设置 `stop` 方法的响应机制：
- `true`：异步。调用 `stop` 后立即收到响应。
- `false`：同步。调用 `stop` 后，你需等待所有录制文件上传至第三方云存储方后会收到响应。声网预期上传时间不超过 20 秒，如果上传超时，你会收到错误码 `206`。
    - Default: `false`

### Request body example

```json
{
  "cname": "<your_channel_name>",
  "uid": "<unique_user_id>",
  "clientRequest": {
    "async_stop": false
  }
}
```

## Responses

### 200

如果返回的 HTTP 状态码为 `200`，表示请求成功。

- `resourceId` (string) - 云端录制使用的 Resource ID。
- `sid` (string) - 录制 ID。标识一次录制周期。
- `serverResponse` (object) - 页面录制场景下会返回的字段。
  - `serverResponse.fileListMode` (string) - `fileList` 字段的数据格式：
- `"string"`：`fileList` 为 String 类型。合流录制模式下，如果 `avFileType` 设置为 `["hls"]`，`fileListMode` 为 `"string"`。
- `"json"`：`fileList` 为 JSON Array 类型。单流或合流录制模式下 `avFileType` 设置为 `["hls","mp4"]` 时，`fileListMode` 为 `"json"`。
  - `serverResponse.fileList` (string) - 录制产生的 M3U8 文件的文件名。
    - `serverResponse.fileList.items` (object)
      - `serverResponse.fileList.items.fileName` (string) - 录制产生的 M3U8 文件和 MP4 文件的文件名。
      - `serverResponse.fileList.items.trackType` (string) - 录制文件的类型。
- `"audio"`：纯音频文件。
- `"video"`：纯视频文件。
- `"audio_and_video"`：音视频文件。
      - `serverResponse.fileList.items.uid` (string) - 用户 UID，表示录制的是哪个用户的音频流或视频流。合流录制模式下，`uid` 为 `"0"`。
      - `serverResponse.fileList.items.mixedAllUser` (boolean) - 用户是否是分开录制的。
- `true`：所有用户合并在一个录制文件中。
- `false`：每个用户分开录制。
      - `serverResponse.fileList.items.isPlayable` (boolean) - 是否可以在线播放。
- `true`：可以在线播放。
- `false`：无法在线播放。
      - `serverResponse.fileList.items.sliceStartTime` (number) - 该文件的录制开始时间，Unix 时间戳，单位为毫秒。
  - `serverResponse.uploadingStatus` (string) - 当前录制上传的状态：
- `"uploaded"`：本次录制的文件已经全部上传至指定的第三方云存储。
- `"backuped"`：本次录制的文件已经全部上传完成，但是至少有一个 TS 文件上传到了声网备份云。声网服务器会自动将这部分文件继续上传至指定的第三方云存储。
- `"stranded"`：v2 新增状态。部分录制文件未上传至指定的第三方云存储，需要结合业务逻辑进行处理。
- `"unknown"`：未知状态。
  - `serverResponse.extensionServiceState` (array)
    - `serverResponse.extensionServiceState.items` (object)
      - `serverResponse.extensionServiceState.items.playload` (object) - **页面录制**模式下，**上传服务**返回的字段。
        - `serverResponse.extensionServiceState.items.playload.fileList` (array)
          - `serverResponse.extensionServiceState.items.playload.fileList.items` (object)
            - `serverResponse.extensionServiceState.items.playload.fileList.items.filename` (string) - 录制产生的 M3U8 文件和 MP4 文件的文件名。
            - `serverResponse.extensionServiceState.items.playload.fileList.items.sliceStartTime` (number) - 该文件的录制开始时间，Unix 时间戳，单位为毫秒。
        - `serverResponse.extensionServiceState.items.playload.onhold` (boolean) - 页面录制是否处于暂停状态：
- `true`：处于暂停状态。
- `false`：处于运行状态。
        - `serverResponse.extensionServiceState.items.playload.state` (string) - 将订阅内容上传至扩展服务的状态：
- `"init"`：服务正在初始化。
- `"inProgress"`：服务启动完成，正在进行中。
- `"exit"`：服务退出。
        - `serverResponse.extensionServiceState.items.playload.uploadingStatus` (string) - 当前录制上传的状态：
- `"uploaded"`：本次录制的文件已经全部上传至指定的第三方云存储。
- `"backuped"`：本次录制的文件已经全部上传完成，但是至少有一个 TS 文件上传到了声网备份云。声网服务器会自动将这部分文件继续上传至指定的第三方云存储。
- `"stranded"`：v2 新增状态。部分录制文件未上传至指定的第三方云存储，需要结合业务逻辑进行处理。
- `"unknown"`：未知状态。
      - `serverResponse.extensionServiceState.items.serviceName` (string) - 服务类型：
- `"upload_service"`：上传服务。
- `"web_recorder_service"`：页面录制服务。
- `cname` (string) - 录制的频道名。
- `uid` (string) - 字符串内容为云端录制服务在 RTC 频道内使用的 UID，用于标识频道内的录制服务。
### 非 200

如果 HTTP 状态码不为 `200`，请参考[响应状态码](/zh-CN/realtime-media/cloud-recording/reference/response-code)排查问题。

No schema.

## Response examples

### 200

```json
{
  "resourceId": "云端录制使用的 Resource ID。",
  "sid": "录制 ID。标识一次录制周期。",
  "serverResponse": {
    "extensionServiceState": [
      {
        "playload": {
          "uploadingStatus": "当前录制上传的状态：\n- `\"uploaded\"`：本次录制的文件已经全部上传至指定的第三方云存储。\n- `\"backuped\"`：本次录制的文件已经全部上传完成，但是至少有一个 TS 文件上传到了声网备份云。声网服务器会自动将这部分文件继续上传至指定的第三方云存储。\n- `\"stranded\"`：v2 新增状态。部分录制文件未上传至指定的第三方云存储，需要结合业务逻辑进行处理。\n- `\"unknown\"`：未知状态。"
        },
        "serviceName": "服务类型：\n- `\"upload_service\"`：上传服务。\n- `\"web_recorder_service\"`：页面录制服务。"
      }
    ]
  },
  "cname": "录制的频道名。",
  "uid": "字符串内容为云端录制服务在 RTC 频道内使用的 UID，用于标识频道内的录制服务。"
}
```