# 创建或重置流配置模板 (/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" } ```