# 更新流配置模板 (/zh-CN/api-reference/api-ref/rtmp-gateway/update-template)

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

更新已创建的流配置模板。

- OpenAPI: /openapi/media-gateway/media-gateway.zh-CN.yaml
- Operation ID: patch-region-v1-projects-appId-rtls-ingress-stream-templates-templateId
- Method: PATCH
- Path: /{region}/v1/projects/{appId}/rtls/ingress/stream-templates/{templateId}
- Endpoint: https://api.sd-rtn.com/{region}/v1/projects/{appId}/rtls/ingress/stream-templates/{templateId}

## Servers

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

:::warning[注意]
- 该接口只能在流配置模板已经存在的情况下调用。
- 流配置模板的修改只有在重新推流后才会生效，且考虑到网关与数据库之间的同步延迟，请在调用该接口 3 分钟后再重新推流。
:::

## Authorization

This endpoint requires authentication.

- `Basic Auth`
- `API Key`

## Parameters

- `X-Request-ID` (header, optional, string) - 本次请求的 UUID（通用唯一识别码）。传入该字段后，声网服务器会在响应 Header 中返回该字段。声网推荐你对 `X-Request-ID` 赋值。如果不赋值，声网服务器会自动生成一个 UUID 传入。
- `region` (path, required, string) - 使用 RTMP 网关的区域。声网支持分区域创建推流码，目前支持以下区域：
- `cn`：中国大陆
- `ap`：除中国大陆以外的亚洲区域
- `na`：北美
- `eu`：欧洲

> [!CAUTION]
> - 请确保设置的 `region` 与输入的源流在同一个区域。
> - 请确保设置的 `region` 与推流使用的域名在同一个区域。
> - 请确保传入 `region` 的值为小写。
- `appId` (path, required, string) - 声网为每个开发者提供的 App ID。在声网控制台创建一个项目后即可得到一个 App ID。App ID 是一个项目的唯一标识。
- `templateId` (path, required, string) - 流配置模板 ID。取值只能为 a-z，A-Z，0-9，且长度不能超过 12 个字节。流配置模板 ID 的值，可根据业务场景需求设置。比如可以根据目标分辨率的不同取值为 "720p", "1080p"；也可以根据不同的游戏场景取值为 "gameA"，"gameB" 等等。

## Request body

请求包体为 JSON Object 类型的 `settings` 字段。

> [!CAUTION]
> - 为确保请求成功，请不要将必填字段设为 `null` 或 `""`。
> - 更新支持的最小单元为：
>   - `transcoding.video`
>   - `transcoding.audio`
>   - `jitterBuffer`
>   举例来说，如果只希望更新 `transcoding.video` 中的 `fps` 字段，也需要再次传入整个 `transcoding.video` ，仅修改 `fps` 字段，其他字段保持不变一起传入。不能单独传入 `fps` 字段。
> - `transcoding.video`、`transcoding.audio`、`jitterBuffer` 之间相互独立，互不影响。如果只传入 `transcoding.video`，那么就只会更新它的参数，不会影响 `transcoding.audio` 和 `jitterBuffer` 的参数值。

- `transcoding` (object) - 音视频转码参数配置。
  - `transcoding.video` (object) - 视频转码参数。
    - `transcoding.video.enabled` (boolean, required) - 是否开启视频转码，默认关闭。
      - Default: `false`
    - `transcoding.video.mode` (string) - 转码模式。
- `force`（默认）：强制开启转码。
- `adaptive`：自适应开启转码。
    - 当源流有 B 帧时，则开启转码。
    - 如果推流开始的 2 秒内有 B 帧，则以转码模式开始推流。
    - 如果推流中途出现 B 帧，则先以不转码模式推流，待有 B 帧后再切换为转码模式，切换过程观众端会感知到主播先暂停发流，再恢复发流。
      - Default: `force`
    - `transcoding.video.codec` (string) - 转码的编解码格式。支持取值：`H.264`，`VP8`。
      - Default: `H.264`
    - `transcoding.video.width` (number) - 视频编码宽度，单位为 px。如不填或填 `0`，则跟随源流的宽度。
      - Range: `[0, 1920]`
    - `transcoding.video.height` (number) - 视频编码高度，单位为 px。如不填或填 `0`，则跟随源流的高度。

> [!CAUTION]
> width 和 height 需要同时填入或同时都不填，目前暂不支持只填其中 1 个。
      - Range: `[0, 1920]`
    - `transcoding.video.fps` (number) - 视频编码帧率，单位为 fps。如不填或填 `0`，则跟随源流的帧率。
      - Range: `[0, 60]`
    - `transcoding.video.bitrate` (number) - 视频编码码率，单位为 Kbps。
- 如果开启小流（提供下面的 `simulcastStream`），则该字段为必填，且要保证值大于 `simulcastStream.bitrate`。
- 如果未开启小流（不提供 `simulcastStream`），则该字段为选填。如果不填，会跟随源流码率；如果填 `0`，会根据 `width`、`height` 和 `fps` 三个字段的值自动匹配声网推荐的码率，详见[常用视频属性](/zh-CN/api-reference/rtmp-gateway/restful/api/video-profile)。
    > [!TIP]
    > 在不开启小流的情况下，建议使用自动匹配的码率，无需自行设置码率。
      - Range: `[0, 14000]`
    - `transcoding.video.simulcastStream` (object) - 视频小流配置项。如果提供，则开启小流，并指定小流的转码参数。
      - `transcoding.video.simulcastStream.width` (number) - 视频小流的宽度，单位为 px。该参数的值需要小于上面 `video.width` 的值。如不填或填 `0`，则采用 `video.width` ÷ 2 的值。
        - Range: `[0, 1920]`
      - `transcoding.video.simulcastStream.height` (number) - 视频小流的高度，单位为 px。该参数的值需要小于上面 `video.height` 的值。如不填或填 `0`，则采用 `video.height` ÷ 2 的值。
        - Range: `[0, 1920]`
      - `transcoding.video.simulcastStream.fps` (number) - 视频小流的帧率，单位为 fps。该参数的值需要小于等于 `video.fps` 的值。如不填或填 `0`，则使用 `15` 作为默认值。
        - Default: `15`
        - Range: `[0, 60]`
      - `transcoding.video.simulcastStream.bitrate` (number) - 视频小流的码率，单位为 Kbps。该参数的值需要小于上面 `video.bitrate` 的值。如果不填或填 `0`，则根据 `video.bitrate`、小流的分辨率和 fps，自动计算声网推荐码率。
> [!CAUTION]
> 当开启小流且指定小流 bitrate 时，需要同时指定 `video.bitrate`。
  - `transcoding.audio` (object) - 音频转码参数。
    - `transcoding.audio.enabled` (boolean, required) - 是否开启音频转码，默认开启。
      - Default: `true`
    - `transcoding.audio.profile` (number) - 编码音频场景。默认值为 `0`，表示 48 KHz 采样率、音乐编码、单声道、编码码率最大值为 64 Kbps。如果要设置其他 `profile`，请[联系技术支持](https://ticket.shengwang.cn)。
      - Default: `0`
    - `transcoding.audio.bitrate` (number) - 编码码率，单位为 Kbps。如果不填，则码率由 `profile` 的值确定。
      - Range: `[64, 320]`
- `jitterBuffer` (object) - 网络抖动缓冲，仅在开启视频转码时生效。
  - `jitterBuffer.size` (number) - `jitterBuffer` 的数据长谷，单位 ms。默认值为 500，表示 RTMP 网关会增加 500 ms 的端到端延迟，以降低网络抖动带来的卡顿。
    - Default: `500`
  - `jitterBuffer.maxSize` (number) - `jitterBuffer` 的最大长度，单位 ms，默认值为1000。请确保该字段的值大于 `jitterBuffer.size`。当 `jitterBuffer` 长度超过此值时，网关就会开启加速，直到恢复至 `jitterBuffer.size`。
    - Default: `1000`

### Request body example

```json
{
  "settings": {
    "transcoding": {
      "video": {
        "enabled": true,
        "codec": "H.264",
        "width": 1280,
        "height": 720,
        "fps": 24,
        "bitrate": 2200,
        "simulcastStream": {
          "width": 960,
          "height": 540,
          "fps": 24,
          "bitrate": 1670
        }
      }
    }
  }
}
```

## Responses

### default

如果状态码不为 `2XX`，则请求失败。你可以参考[响应状态码](/zh-CN/realtime-media/rtmp-gateway/reference/response-code)了解可能的原因。

- `message` (string) - 请求失败的具体原因。
### 2XX

如果状态码为 `2XX`，则请求成功。

- `status` (string) - 请求状态，值为 `success`。

## Response examples

### default

```json
{
  "message": "string"
}
```
### 2XX

```json
{
  "status": "success"
}
```