# 更新流配置模板 (/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" } ```