# 创建 Converter (/zh-CN/api-reference/api-ref/media-push/create) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 在项目中创建一个 Converter，用于处理音视频流并推流到 CDN。 - OpenAPI: /openapi/media-push/media-push.zh-CN.yaml - Operation ID: post-region-v1-projects-appId-rtmp-converters - Method: POST - Path: /{region}/v1/projects/{appId}/rtmp-converters - Endpoint: https://api.sd-rtn.com/{region}/v1/projects/{appId}/rtmp-converters ## Servers - https://api.sd-rtn.com `Create` 请求的 Body 字段设置较为复杂，请阅读如下文档后再进一步了解本文的字段说明： - [设置不转码推流](/zh-CN/realtime-media/media-push/build/configure-media-stream/set-no-transcode) - [设置转码推流](/zh-CN/realtime-media/media-push/build/configure-media-stream/update-transcode) - [设置混音音量](/zh-CN/realtime-media/media-push/build/configure-media-stream/set-volume) - [设置 SEI 信息](/zh-CN/realtime-media/media-push/build/configure-media-stream/set-sei) ## Authorization This endpoint requires authentication. - `Basic Auth` ## Parameters - `Content-Type` (header, required, string) - `application/json` - `X-Request-ID` (header, optional, string) - UUID（通用唯一识别码），标识本次请求。推荐你赋值，赋值后，声网服务器会在响应 Header 中返回一个对应的 `X-Custom-Request-ID` 字段，你可以用此进行问题排查。如果你不赋值，那么声网服务器会自动生成一个 UUID 并在响应 Header 中返回一个对应的 `X-Request-ID` 字段。 - `regionHintIp` (query, optional, string) - CDN 源站 IP 地址，必须为有效的 IPv4 地址。该参数可以保障 RTMP 流的稳定性。 - `region` (path, required, string) - 创建 Converter 的区域。声网支持分区域创建 Converter。请保证设置的 `region` 与你的 CDN 源站在同一个区域且传入 `region` 的值为小写。目前支持以下区域： - `cn`：中国大陆 - `ap`：除中国以外的亚洲区域 - `na`：北美 - `eu`：欧洲 - `appId` (path, required, string) - 声网为每个开发者提供的 **App ID**。在声网控制台创建一个项目后即可得到一个 App ID。一个 App ID 是一个项目的唯一标识。 ## Request body `Create` 请求可创建**转码**推流和**不转码**推流的 Converter。 - `converter` (object, required) - **转码**推流时需设置如下字段。 - `converter.name` (string) - Converter 的名字。长度必须在 64 个字符以内，支持的字符集范围如下： - 所有小写英文字母（a-z） - 所有大写英文字母（A-Z） - 数字 0-9 - "-", "_" > [!CAUTION] > - 不传值时该字段为空。 > - 同一时间，一个项目下不允许出现重名的 Converter，否则在尝试创建同名的 Converter 时会收到响应状态码 `409(Conflict)`。 > - 为避免重复创建多个 Converter 重复推流，请使用 `name` 字段管理指定项目下的 Converter。声网推荐你以“频道名（`rtcChannel`）”和 “Converter 特性”组合来给 `name` 赋值。如 `show68_horizontal` 和 `show68_vertical`，分别代表在频道 `show68` 中创建的用户画面为水平布局和和垂直布局的 Converter。 - `converter.transcodeOptions` (object, required) - **转码**推流的配置。 - `converter.transcodeOptions.rtcChannel` (string, required) - 声网频道名称，即 Converter 处理的流所属频道的名称。字符串长度必须在 64 字节以内，支持以下字符集（共 89 个字符）： - 所有小写英文字母（a-z） - 所有大写英文字母（A-Z） - 数字 0-9 - 空格 - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "\|", "~", "," - `converter.transcodeOptions.audioOptions` (object) - Converter 的音频转码配置。 **注意**： - 该字段仅需在有音频的场景下设置。如果有音频但是无需自定义音频配置，那么将该字段设为空，即 `"audioOptions": {}`。 - 暂时只支持不超过 3 名用户进行混音，如果参与混音的用户人数大于 3，请联系[技术支持](https://ticket.shengwang.cn)。 - `converter.transcodeOptions.audioOptions.rtcStreamUids` (array) - 指定参与混音的用户 UID。 **注意**： - 如果 `audioOptions` 中无该字段，声网将频道内所有用户音频进行混音。 - 如果 `audioOptions` 中存在该字段且值为空，则代表不混合任何用户的音频流。 - `converter.transcodeOptions.audioOptions.rtcStreamUids.items` (number) - `converter.transcodeOptions.audioOptions.codecProfile` (string) - Converter 输出的音频编解码规格。支持如下值： - `"LC-AAC"`: MPEG-4 AAC LC。 - `"HE-AAC"`: High-Efficiency AAC。 - Default: `LC-AAC` - `converter.transcodeOptions.audioOptions.sampleRate` (number) - Converter 输出的音频编码采样率 (Hz)，支持取值如下： - `32000` - `44100` - `48000` - Default: `48000` - `converter.transcodeOptions.audioOptions.bitrate` (number) - Converter 输出的音频编码码率 (Kbps)。取值范围为 [32,128]。推荐取值如下： - 如果音频编解码器为 LC-AAC，推荐取值范围为 [32,112]。 - 如果音频编解码器为 HE-AAC，推荐取值范围为 [40,96]。 - Default: `48` - `converter.transcodeOptions.audioOptions.audioChannels` (number) - Converter 输出的音频声道数，支持取值如下： - `1`：单声道。 - `2`：双声道。 - Default: `1` - `converter.transcodeOptions.audioOptions.volumes` (array) - 参与混音的用户音量。 **注意**：发起 `Update` 请求更新指定用户音量时，每次请求成功都会将其他用户（非指定用户）的音量恢复成默认音量 `100`。 - `converter.transcodeOptions.audioOptions.volumes.items` (object) - `converter.transcodeOptions.audioOptions.volumes.items.rtcStreamUid` (number, required) - 待设置音量的混音用户 UID。 **注意**：填入的 UID 需要存在于 `rtcStreamUids`（参与混音的用户 UID 数组）中，否则请求失败。 - `converter.transcodeOptions.audioOptions.volumes.items.volume` (number) - 指定的混音用户的音量。取值范围为 [0,200]。 - Default: `100` - `converter.transcodeOptions.videoOptions` (object) - Converter 的视频转码配置。 **注意**：该字段仅需在有视频的场景下设置。并且在音视频场景下，该字段不能为空。 - `converter.transcodeOptions.videoOptions.canvas` (object, required) - 视频画布的配置。 - `converter.transcodeOptions.videoOptions.canvas.width` (number, required) - 画布的宽度 (pixel)。取值范围为 [66,1920]。 - `converter.transcodeOptions.videoOptions.canvas.height` (number, required) - 画布的高度 (pixel)。取值范围为 [66,1920]。 - `converter.transcodeOptions.videoOptions.canvas.color` (number) - 画布的背景色。RGB 颜色值，以十进制数表示。如 255 代表蓝色。取值范围为 [0,16777215]。默认值为 0，即黑色。 - Default: `0` - `converter.transcodeOptions.videoOptions.layoutType` (number) - 输出视频的画面布局类型： - `0` 或空：自定义布局，即通过 `layout` 自定义布局。 - `1`：垂直布局，即通过 `vertical` 指定一个用户在屏幕左侧显示大视窗画面，其他用户以小视窗画面在屏幕右侧垂直排列，详见[设置垂直布局](/zh-CN/realtime-media/media-push/build/configure-media-stream/vertical-streaming)。垂直布局时，通过 `Update` 请求只能更新 `rtmpUrl`。 - Default: `0` - `converter.transcodeOptions.videoOptions.layout` (array) - 画布上各用户的视频画面的配置。 > [!CAUTION] > 仅需在 `layoutType` 为自定义布局时设置 `layout` 字段。 - `converter.transcodeOptions.videoOptions.layout.items` (object) - `converter.transcodeOptions.videoOptions.layout.items.rtcStreamUid` (number, required) - 用户 UID。 - `converter.transcodeOptions.videoOptions.layout.items.region` (object, required) - 用户视频画面在画布上的显示区域。超出画布的视频画面会被裁剪。 - `converter.transcodeOptions.videoOptions.layout.items.region.xPos` (number, required) - 画面在画布上的 x 坐标 (pixel)。以画布左上角为原点，x 坐标为画面左上角相对于原点的横向位移。 - `converter.transcodeOptions.videoOptions.layout.items.region.yPos` (number, required) - 画面在画布上的 y 坐标 (pixel)。以画布左上角为原点，y 坐标为画面左上角相对于原点的纵向位移。 - `converter.transcodeOptions.videoOptions.layout.items.region.zIndex` (number, required) - 画面的图层编号。取值范围为 [0,100]。`0` 代表最下层的图层。`100` 代表最上层的图层。 - `converter.transcodeOptions.videoOptions.layout.items.region.width` (number, required) - 画面的宽度 (pixel)。 - `converter.transcodeOptions.videoOptions.layout.items.region.height` (number, required) - 画面的高度 (pixel)。 - `converter.transcodeOptions.videoOptions.layout.items.fillMode` (string) - 用户视频画面的显示模式： - `"fill"`：在保持宽高比的前提下，缩放画面，并居中剪裁。详见[示意图](https://web-cdn.agora.io/docs-files/1628837665989)。 - `"fit"`：在保持宽高比的前提下，缩放画面，使其完整显示。详见[示意图](https://web-cdn.agora.io/docs-files/1628837708782)。 - Default: `fill` - `converter.transcodeOptions.videoOptions.layout.items.placeholderImageUrl` (string) - 用户画面的背景图 URL 地址。支持 JPG、PNG 和 GIF 格式的图片。当频道内用户停止发布视频流，如果设置了该字段，用户的视频画面将切换为该背景图，否则会显示为画布背景色。 - `converter.transcodeOptions.videoOptions.layout.items.alpha` (number) - 透明度。`0.0` 代表完全透明，`1.0` 代表完全不透明。 - Default: `1` - Format: `float` - Range: `[0, 1]` - `converter.transcodeOptions.videoOptions.vertical` (object) - 垂直布局的画面配置。 > [!CAUTION] > 仅需在 `layoutType` 为垂直布局时设置 `vertical` 字段。 - `converter.transcodeOptions.videoOptions.vertical.maxResolutionUid` (number) - 显示大视窗画面的用户 UID。 **注意**：如果未设置，则每次布局画面刷新时将音量最大的用户显示为大视窗画面。为维持大视窗画面稳定，建议你设置该字段。 - `converter.transcodeOptions.videoOptions.vertical.fillMode` (string) - 用户视频画面的显示模式： - `"fill"`：在保持宽高比的前提下，缩放画面，并居中剪裁。详见[示意图](https://web-cdn.agora.io/docs-files/1628837665989)。 - `"fit"`：在保持宽高比的前提下，缩放画面，使其完整显示。详见[示意图](https://web-cdn.agora.io/docs-files/1628837708782)。 - Default: `fill` - `converter.transcodeOptions.videoOptions.vertical.refreshIntervalSec` (number) - 布局画面刷新的时间间隔，单位为秒。 - Default: `3` - Range: `[1, 30]` - `converter.transcodeOptions.videoOptions.defaultPlaceholderImageUrl` (string) - 默认的用户画面背景图 URL 地址。支持 JPG、PNG 和 GIF 格式的图片。当频道内用户停止发布视频流时，背景图的行为如下： - 如果设置了该字段，用户的视频画面将切换为该背景图。 - 如果未设置该字段，用户的视频画面先显示为该用户视频最后一帧，布局刷新后显示为画布背景色。 - `converter.transcodeOptions.videoOptions.bitrate` (number, required) - 输出视频的编码码率 (Kbps)。取值范围为 [1,10000]。推荐取值详见[常用视频属性](/zh-CN/api-reference/media-push/restful/api/video-profile)。 - `converter.transcodeOptions.videoOptions.frameRate` (number) - 输出视频的编码帧率 (fps)。取值范围为 [1,30]。推荐取值详见[常用视频属性](/zh-CN/api-reference/media-push/restful/api/video-profile)。 - Default: `15` - `converter.transcodeOptions.videoOptions.gop` (number) - 输出视频的 GOP。默认值为 `framerate` 的 2 倍。 - `converter.transcodeOptions.videoOptions.codec` (string) - 输出视频的编解码规格。不可设置为空。支持如下值： - `"H.264"` - `"H.265"` - Default: `H.264` - `converter.transcodeOptions.videoOptions.codecProfile` (string) - 输出视频的编码规格。支持如下值： - `"high"`: High 级别的视频编码规格，一般用于广播及视频碟片存储，高清电视。 - `"baseline"`: Baseline 级别的视频编码规格，一般用于低阶或需要额外容错的应用，比如视频通话、手机视频等。 - `"main"`: Main 级别的视频编码规格，一般用于主流消费类电子产品，如 mp4、便携的视频播放器、PSP 和 iPad 等。 **注意**：如果 `codec` 为 H.265，那么该字段默认值且唯一支持取值为 `"main"`。如果 `codec` 为 H.264，那么该字段默认值为 `"high"`。 - `converter.transcodeOptions.videoOptions.seiOptions` (object) - 设置携带的用户 SEI（Supplemental Enhancement Information）信息。默认为空。不设置则不携带用户 SEI 信息。 - `converter.transcodeOptions.videoOptions.seiOptions.source` (object) - 设置 SEI 信息的数据来源。默认为空。 - `converter.transcodeOptions.videoOptions.seiOptions.source.metadata` (boolean) - 是否传入 Metadata 类型的 SEI 信息。 - `true`：传入。 - `false`：不传入。 - Default: `false` - `converter.transcodeOptions.videoOptions.seiOptions.source.datastream` (boolean) - 是否传入 Datastream 类型的 SEI 信息。 - `true`：传入。 - `false`：不传入。 - Default: `false` - `converter.transcodeOptions.videoOptions.seiOptions.source.customized` (object) - 自定义 SEI 信息。默认为空。 自定义 SEI 信息会被转换为[声网 SEI 规范](/zh-CN/reference/faq/quality/sei)的 SEI 信息。 - `converter.transcodeOptions.videoOptions.seiOptions.source.customized.prefixForAgoraSei` (string) - 自定义 SEI 信息的 payload 前缀。长度必须在 32 个字符以内。默认为空。 - `converter.transcodeOptions.videoOptions.seiOptions.source.customized.payload` (string) - 自定义 SEI 信息的 payload。长度必须在 4096 个字符以内。默认为空。 自定义 SEI 信息会被转换为[声网 SEI 规范](/zh-CN/reference/faq/quality/sei)的 SEI 信息。此处设置的 payload 会被转换至声网 SEI 规范中定义的 `app_data` 中。 - `converter.transcodeOptions.videoOptions.seiOptions.sink` (object) - 设置输出的 SEI 信息。默认为空。 - `converter.transcodeOptions.videoOptions.seiOptions.sink.type` (number) - 输出 SEI 信息的 payload 的 `type`。 - Default: `100` - `converter.rtmpUrl` (string, required) - CDN 推流地址。必须为有效的 RTMP 地址，且长度在 1024 个字符以内。如果你从 OBS 推流更换为旁路推流，需要按照 `{server}/{stream_key}` 的规则来拼接 RTMP URL。 - `converter.idleTimeout` (number) - Converter 处于空闲状态的最大时长（秒）。空闲指 Converter 处理的音视频流所对应的所有用户均已离开频道。当 Converter 处于空闲状态时长大于 `idleTimeout`，Converter 自动销毁，推流停止。取值范围为 [5,86400]。如果设置值小于 5，则默认为 5；如果设置值大于 86400，则默认为 86400。 - Default: `300` - `converter.jitterBufferSizeMs` (number) - 音频接收端到网络抖动缓冲端的网络延迟 (ms)。取值范围 [0,1000]。旁路推流服务会根据你设置的值，以 100 为单位向上取整。 **注意**：声网建议你不要设为 `0`。设为 `0` 表示不使用抖动缓冲延迟，弱网情况下可能导致音画质量问题， - Default: `1000` ### Request body example ```json { "converter": { "name": "show68_vertical", "transcodeOptions": { "rtcChannel": "show68", "audioOptions": { "codecProfile": "HE-AAC", "sampleRate": 48000, "bitrate": 128, "audioChannels": 1, "rtcStreamUids": [ 201, 202 ], "volumes": [ { "volume": 50, "rtcStreamUid": 201 }, { "volume": 150, "rtcStreamUid": 202 } ] }, "videoOptions": { "canvas": { "width": 360, "height": 640, "color": 0 }, "layout": [ { "rtcStreamUid": 201, "region": { "xPos": 0, "yPos": 0, "zIndex": 1, "width": 360, "height": 320 }, "fillMode": "fill", "placeholderImageUrl": "http://example.agora.io/host_placeholder.jpg" }, { "rtcStreamUid": 202, "region": { "xPos": 0, "yPos": 320, "zIndex": 1, "width": 360, "height": 320 } }, { "imageUrl": "http://example.agora.io/watchmark.jpg", "region": { "xPos": 0, "yPos": 0, "zIndex": 2, "width": 36, "height": 64 }, "fillMode": "fit" } ], "codec": "H.264", "codecProfile": "high", "frameRate": 15, "gop": 30, "bitrate": 400, "seiOptions": { "source": { "metadata": true, "datastream": true, "customized": { "payload": "example" } }, "sink": { "type": 100 } } } }, "rtmpUrl": "rtmp://example/live/show68", "idleTimeout": 300 } } ``` ## Responses ### 2XX 如果状态码为 2XX，请求成功。 - `converter` (object) - `converter.id` (string) - Converter 的 ID，是声网服务器生成的一个 UUID（通用唯一识别码），标识一个已创建的 Converter。 - `converter.createTs` (string) - 创建 Converter 时的 Unix 时间戳（秒）。 - `converter.updateTs` (string) - 最近一次更新 Converter 配置时的 Unix 时间戳（秒）。 - `converter.state` (string) - Converter 的运行状态： - `"connecting"`: 正在连接声网推流服务器和 CDN 服务器。 - `"running"`: 正在进行推流。 - `"failed"`: 推流失败。 - `fields` (string) - JSON 编码方式的字段掩码，详见[谷歌 protobuf FieldMask 文档](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask)。用于描述返回的 `converter` object 中包含的字段集合。 示例： ```json { "converter": { "id": "4c014467d647bb87b60b719f6fa57686", "createTs": 1591786766, "updateTs": 1591788746, "state": "running" }, "fields": "id,createTs,updateTs,state" } ``` 在本示例中，`fields` 描述返回的 `converter` object 中包含 `id`、`createTs`、`updateTs`、`state` 字段。 ### 非 2XX 如果状态码不为 2XX，请求失败。 - `message` (string) - 描述请求失败的具体原因。 ## Response examples ### 2XX ```json { "converter": { "id": "Converter 的 ID，是声网服务器生成的一个 UUID（通用唯一识别码），标识一个已创建的 Converter。", "createTs": "创建 Converter 时的 Unix 时间戳（秒）。", "updateTs": "最近一次更新 Converter 配置时的 Unix 时间戳（秒）。", "state": "Converter 的运行状态：\n- `\"connecting\"`: 正在连接声网推流服务器和 CDN 服务器。\n- `\"running\"`: 正在进行推流。\n- `\"failed\"`: 推流失败。" }, "fields": "JSON 编码方式的字段掩码，详见[谷歌 protobuf FieldMask 文档](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask)。用于描述返回的 `converter` object 中包含的字段集合。

\n示例：\n```json\n{\n \"converter\": {\n \"id\": \"4c014467d647bb87b60b719f6fa57686\",\n \"createTs\": 1591786766,\n \"updateTs\": 1591788746,\n \"state\": \"running\"\n },\n \"fields\": \"id,createTs,updateTs,state\"\n}\n```\n在本示例中，`fields` 描述返回的 `converter` object 中包含 `id`、`createTs`、`updateTs`、`state` 字段。" } ``` ### 非 2XX ```json { "message": "描述请求失败的具体原因。" } ```