# 创建或重置流配置模板 (/zh-CN/api-reference/api-ref/rtmp-gateway/create-reset-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: put-region-v1-projects-appId-rtls-ingress-stream-templates-templateId
- Method: PUT
- 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/

该方法创建一个流配置模板（Stream Template）。在流配置模板中，你可以配置视频或音频流的转码参数，以及用于缓解网络延迟的参数。

每个 App ID 下最多可以创建 10 个流配置模板，每个流配置模板都有唯一的 ID 标识（templatedId）。在创建流配置模板时，你需要为其指定一个 templateId。如果该 templateId 对应的模板已经存在，则会以传入的 Body 数据重置整个流配置模板的值。

流配置模板有两种使用方式，可结合使用：

- **为 App ID 指定全局的流配置模板**：该 App ID 下所有的推流码（Stream Key），默认都会使用该模板；
- **为特定的推流码指定特定的流配置模板**：使用该推流码推流时，就会使用特定的流配置模板。


:::warning[注意]
所有 App ID 默认情况下不设置流配置模板，即不会默认开启视频转码。
:::

## 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` (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
        }
      },
      "audio": {
        "enabled": true,
        "profile": 3
      }
    },
    "jitterBuffer": {
      "size": 500,
      "maxSize": 800
    }
  }
}
```

## 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"
}
```