文档中心
互动直播
Console Agora.io 社区 提交工单
简体中文
search-icon

旁路推流 RESTful API

更新时间 2022/06/15 02:49:32

本文介绍如何通过 RESTful API 实现旁路推流。

开通服务

第一次使用旁路推流，需要开通服务，步骤如下：

  1. 登录控制台，在项目管理页面，选择需要开通输入旁路推流服务的项目，点击配置。

  2. 在编辑项目页面的实时互动拓展能力模块找到旁路推流，点击启用。

  1. 启用服务端 RESTful API。启用后不能关闭。

  2. 仔细阅读弹窗提示，点击保存。成功开启旁路推流服务后，启用按钮会切换为配置按钮，用于配置旁路推流。

开通成功后你可以在用量页面看到旁路推流的使用情况。

通过 Basic HTTP 认证

Agora RESTful API 要求 Basic HTTP 认证。每次发送 HTTP 请求时，都必须在请求头部填入 Authorization 字段。关于如何生成该字段的值，请参考 RESTful API 认证。

工作原理

你可以使用推流 RESTful API 订阅 Agora 频道内的音视频流，将音视频流转码后（或选择不转码），通过标准协议（如 RTMP）推送到 CDN（Content Delivery Network）。这个过程相当于 Agora 通过一个 Converter 将音视频流处理后输出并推到 CDN。你可以通过如下方法控制 Converter：

  • Create：为指定的项目创建一个 Converter，设置转码（或不转码）和推流的相关参数。频道内用户音视频流会按照指定的配置经过 Converter 处理后输出推到 CDN。
  • Delete：销毁指定的 Converter。销毁该 Converter 后，此频道内用户音视频流将不再经过 Converter 处理并输出推到 CDN。
  • Update：更新指定的 Converter 配置。
  • Get: 获取指定 Converter 的推流状态。

Create：创建一个 Converter

HTTP 请求

POST https://api.agora.io/{region}/v1/projects/{appId}/rtmp-converters

路径参数

  • appId: String 型必填参数。Agora 为每个开发者提供的 App ID。在 Agora 控制台创建一个项目后即可得到一个 App ID。一个 App ID 是一个项目的唯一标识。

  • region: String 型必填参数。创建 Converter 的区域。Agora 支持分区域创建 Converter，目前支持以下区域：

    • cn：中国大陆
    • ap：除中国大陆以外的亚洲区域
    • na：北美
    • eu：欧洲
  • 请保证设置的 region 与你的 CDN 源站在同一个区域。
  • 请保证传入 region 的值为小写。

    • 查询参数

    regionHintIp: String 型可选参数。CDN 源站 IP 地址，必须为有效的 IPv4 地址。该参数可以保障 RTMP 流的稳定性。

    POST https://api.agora.io/{region}/v1/projects/{appId}/rtmp-converters?regionHintIp={regionHintIp}

    请求头

    • Content-Type: application/json

    • Authorization: 该字段的值需参考认证说明。

    • X-Request-ID: UUID（通用唯一识别码），标识本次请求。Agora 服务器会自动生成一个 UUID，并在响应 header 中返回 X-Request-ID 字段。

      Agora 推荐你对 X-Request-ID 赋值，Agora 服务器会在响应 header 中返回一个 X-Custom-Request-ID 字段，以用于问题排查。

    请求包体

    旁路推流分为转码推流和不转码推流。一般来说，多人连麦直播的场景下，旁路推流时需要转码；单主播直播时，只向 CDN 推送一路媒体流，无需转码。详见功能描述。

    转码推流


    转码推流的请求包体为 JSON Object 类型的 converter 字段，字段结构如图所示：

    字段含义详见下表：

    字段 类型 描述               
    name String（可选） Converter 的名字。长度必须在 64 个字符以内，支持的字符集范围为：
  • 所有小写英文字母（a-z）
  • 所有大写英文字母（A-Z）
  • 数字 0-9
  • "-", "_"
    • 不传值时该字段为空。
  • 同一时间，一个项目下不允许出现重名的 Converter，否则在尝试创建同名的 Converter 时会收到响应状态码 409(Conflict)。
  • 为避免重复创建多个 Converter 重复推流，请使用 name 字段管理指定项目下的 Converter。Agora 推荐你以“频道名（rtcChannel）”和 “Converter 特性”组合来给 name 赋值。如 show68_horizontal 和 show68_vertical，分别代表在频道 show68 中创建的用户画面为水平布局和和垂直布局的 Converter。
    		•
    transcodeOptions JSON Object（必填） Converter 的转码配置。
    transcodeOptions.rtcChannel String（必填） Agora 频道名称。即 Converter 处理的流所属的频道。字符串长度必须在 64 字节以内，支持以下字符集（共 89 个字符）：
  • 所有小写英文字母（a-z）
  • 所有大写英文字母（A-Z）
  • 数字 0-9
  • 空格
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    		•
    transcodeOptions.audioOptions JSON Object Converter 的音频转码配置。详见 audioOptions。
  • 在纯视频流（无音频）场景中，无需设置 audioOptions 及其相关字段。
  • 在音视频场景中，audioOptions 为必填字段，若无字段要求，可以把 audioOptions 设置为空，例如："audioOptions":{}
  • 当 converter.transcodeOptions.audioOptions 字段中无 rtcStreamUids 字段时，Agora 会将频道内所有用户的音频流进行混音并通过 Converter 输出混音后的音频流。
  • 当 converter.transcodeOptions.audioOptions 字段中有 rtcStreamUids 字段时，Agora 会将指定用户的音频流进行混音并通过 Converter 输出混音后的音频流。
    		•
    transcodeOptions.audioOptions.
    codecProfile    		 String（可选） Converter 输出的音频编解码器。支持如下值：
  • LC-AAC（默认值）: MPEG-4 AAC LC。
  • HE-AAC: High-Efficiency AAC。
    		•
    transcodeOptions.videoOptions JSON Object（可选） Converter 的视频转码配置。
  • 在纯音频流（无视频）场景中，无需设置 videoOptions 及其相关字段。
  • 在音视频场景中，videoOptions 为必填字段，且不能为空。
    • transcodeOptions.videoOptions.canvas JSON Object（必填） 视频画布。详见 canvas。
    transcodeOptions.videoOptions.layoutType Number（可选） 输出视频的画面布局类型：
  • 0 或空（默认）：自定义布局，即通过 transcodeOptions.videoOptions.layout 设置布局信息。
  • 1：垂直布局。指定一个用户在屏幕左侧显示大视窗画面，其他用户以小视窗画面在屏幕右侧垂直排列，详见设置垂直布局。
    		•
    transcodeOptions.videoOptions.layout JSON Array（可选） 画布上视频画面的内容描述。详见 layout。支持 RtcStreamView 和 ImageView 两种元素：
  • RtcStreamView 元素：画布上各用户的视频画面。
  • ImageView 元素：画布上的视频图片，可用于当水印。
    如果 layoutType 为0 或空，则该字段为必填。
    • transcodeOptions.videoOptions.vertical JSON Object（可选） 垂直布局的画面设置信息。当 layoutType 为 1 时必须设置该参数。详见 vertical。
    transcodeOptions.videoOptions.
    defaultPlaceholderImageUrl    		 String（可选） 默认的用户画面背景图 URL 地址。支持 JPG、PNG 和 GIF 格式的图片。当频道内用户停止发布视频流：
  • 如果设置了该字段，用户的视频画面将切换为该背景图。
  • 如果未设置该字段，用户的视频画面先显示为该用户视频最后一帧，布局刷新后显示为画布背景色。
    		•
    transcodeOptions.videoOptions.bitrate Number（必填） 输出视频的编码码率 (Kbps)。取值范围为 [1,10000]。详见常用视频属性。
    transcodeOptions.videoOptions.
    frameRate    		 Number（可选） 输出视频的编码帧率 (fps)。取值范围为 [1,30]。默认值为 15。详见常用视频属性。
    transcodeOptions.videoOptions.
    gop    		 Number（可选） 输出视频的 GOP。默认值为 frameRate * 2。
    transcodeOptions.videoOptions.
    codec    		 String（可选） 输出视频的编解码规格。不可设置为空。支持如下值：
  • H.264（默认值）
  • H.265
    		•
    transcodeOptions.videoOptions.
    codecProfile    		 String（可选） 输出视频的编码规格。支持如下值：
  • high（默认值）: High 级别的视频编码规格，一般用于广播及视频碟片存储，高清电视。
  • baseline: Baseline 级别的视频编码规格，一般用于低阶或需要额外容错的应用，比如视频通话、手机视频等。
  • main: Main 级别的视频编码规格，一般用于主流消费类电子产品，如 mp4、便携的视频播放器、PSP 和 iPad 等。
    • 如果 codec 设置为 H.265，则 codecProfile 默认且必须为 main。
    transcodeOptions.videoOptions.seiOptions JSON Object（可选） 设置输出视频中携带的用户 SEI 信息。默认为空。不设置则表示不输出 SEI 信息。详见 seiOptions。
    idleTimeout Number（可选） Converter 处于空闲状态的最大时长（秒）。空闲指 Converter 处理的音视频流所对应的所有用户均已离开频道。当 Converter 处于空闲状态时长大于 idleTimeout，Converter 自动销毁，推流停止。取值范围为 [5,86400]。如果设置值小于 5，则默认为 5；如果设置值大于 86400，则默认为 86400。默认值为 300。
    rtmpUrl String（必填） CDN 推流地址。必须为有效的 RTMP 地址，且长度在 1024 个字符以内。
    jitterBufferSizeMs Int（可选） 音频接收端到网络抖动缓冲端的网络延迟 (ms)。默认值为 1000，取值范围 [0, 1000]。
  • 旁路推流服务会根据你设置的值，以 100 为单位向上取整。
  • 设置为 0 表示不使用抖动缓冲延迟。弱网情况下可能导致音画质量问题，声网建议你不要将 jitterBufferSizeMs 设置为 0。
    		•

    不转码推流

    不转码推流的请求包体为 JSON Object 类型的 converter 字段，字段结构如图所示：

    字段含义详见下表：

    字段 类型 描述               
    name String（可选） Converter 的名字。长度必须在 64 个字符以内，支持的字符集范围为：
  • 所有小写英文字母（a-z）
  • 所有大写英文字母（A-Z）
  • 数字 0-9
  • "-", "_"
    • 不传值时该字段为空。
    同一时间，一个项目下不允许出现重名的 Converter，否则在尝试创建同名的 Converter 时会收到响应状态码 409(Conflict)。
  • 为避免重复创建多个 Converter 重复推流，请使用 name 字段管理指定项目下的 Converter。
    		•
    rawOptions JSON Object（必填） Converter 的推流配置。
    rawOptions.rtcChannel String（必填） Agora 频道名称。即 Converter 处理的流所属的频道。字符串长度必须在 64 字节以内，支持以下字符集（共 89 个字符）：
  • 所有小写英文字母（a-z）
  • 所有大写英文字母（A-Z）
  • 数字 0-9
  • 空格
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    		•
    rawOptions.rtcStreamUid Number（必填） 要推送的音视频流所属用户的 UID。
    rtmpUrl String（必填） CDN 推流地址。必须为有效的 RTMP 地址，且长度在 1024 个字符以内。
    idleTimeout Number（可选） Converter 处于空闲状态的最大时长（秒）。空闲指 Converter 处理的音视频流所对应的所有用户均已离开频道。当 Converter 处于空闲状态时长大于 idleTimeout，Converter 自动销毁，推流停止。取值范围为 [5,86400]。如果设置值小于 5，则默认为 5；如果设置值大于 86400，则默认为 86400。默认值为 300。
    jitterBufferSizeMs Int（可选） 音频接收端到网络抖动缓冲端的网络延迟 (ms)。默认值为 1000，取值范围 [0, 1000]。
  • 旁路推流服务会根据你设置的值，以 100 为单位向上取整。
  • 设置为 0 表示不使用抖动缓冲延迟。弱网情况下可能导致音画质量问题，声网建议你不要将 jitterBufferSizeMs 设置为 0。
    		•

    HTTP 响应

    所有可能的响应状态码详见状态码汇总表。

    响应头

    • X-Request-ID：UUID（通用唯一识别码），标识本次请求。该值为本次请求 header 中 X-Request-ID。如果请求出错，请在日志中打印出该值，排查问题。

      如果本次请求的响应状态码不是 2XX，那么响应 header 中可能无该字段。

    • X-Resource-ID：UUID（通用唯一识别码），标识本次请求创建的 Converter 的 ID。

    响应包体

    如果状态码为 2XX，则请求成功。响应包体中包含字段结构如图所示：

    字段含义详见下表：

    字段 类型 描述               
    converter.id String Converter 的 ID。它是 Agora 服务器生成的一个 UUID（通用唯一识别码），标识一个已创建的 Converter。
    converter.createTs Number 创建 Converter 时的 Unix 时间戳（秒）。
    converter.updateTs Number 最近一次更新 Converter 配置时的 Unix 时间戳（秒）。
    converter.state String Converter 的运行状态：
  • idle: 推流未开始或已结束。
  • connecting: 正在连接 Agora 推流服务器和 CDN 服务器。
  • running: 正在进行推流。
  • failed: 推流失败。
    		•
    fields String JSON 编码方式的字段掩码，详见谷歌 protobuf FieldMask 文档。用于描述返回的 converter 中包含的字段集合。在本示例中，fields 指定了 Agora 服务器返回 converter 字段中的 id，createTs，updateTs 和 state 字段子集。

    如果状态码不为 2XX，则请求失败。包体中包含 String 类型的 message 字段，描述失败的具体原因。

    {
    "message": "Invalid authentication credentials."
}

    请求示例

    自定义布局的转码推流

    该示例展示将 show68 频道内指定的两个用户使用自定义布局进行合图后推到 CDN，将频道指定的两个用户音频进行混音，且分别指定两个用户的音量大小：

    {
    "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
    }
}

    转码推流且垂直布局

    该示例展示将 show68 频道内指定的两个用户使用垂直布局进行合图后推到 CDN，并且将频道内指定的两个用户的音频进行混音：

    {
    "converter": {
        "name": "show68_vertical",
        "transcodeOptions": {
            "rtcChannel": "show68",
            "audioOptions": {
                "codecProfile": "HE-AAC",
                "sampleRate": 48000,
                "bitrate": 128,
                "audioChannels": 1,
                "rtcStreamUids": [
                    201,
                    202
                ]
            },
            "videoOptions": {
                "canvas": {
                    "width": 360,
                    "height": 640,
                    "color": 0
                },
                "layout": [
                    {
                        "rtcStreamUid": 201,
                        "region": {
                            "xPos": 0,
                            "yPos": 0,
                            "zIndex": 1,
                            "width": 360,
                            "height": 640
                        },
                        "fillMode": "fill",
                        "placeholderImageUrl": "http://example/host_placeholder.jpg"
                    },
                                     {
                        "rtcStreamUid": 202,
                        "region": {
                            "xPos": 0,
                            "yPos": 320,
                            "zIndex": 1,
                            "width": 360,
                            "height": 320
                        }
                    }
                ],
                "codec": "H.264",
                "codecProfile": "high",
                "frameRate": 15,
                "gop": 30,
                "bitrate": 400,
                "layoutType": 1,
                "vertical": {
                    "maxResolutionUid": 201,
                    "fillMode": "fill",
                    "refreshIntervalSec": 4
                },
                "defaultPlaceholderImageUrl": "http://example/host_placeholder.jpg",
                "seiOptions": {
                    "source": {
                        "metadata": true,
                        "datastream": true,
                        "customized": {
                            "payload": "example"
                        }
                    },
                    "sink": {
                        "type": 100
                    }
                }
            }
        },
        "rtmpUrl": "rtmp://example/live/show68",
        "idleTimeout": 300
    }
}

    转码推流且自定义布局

    不转码推流

    该示例展示将 show68 频道内指定用户的音视频流推送到 CDN。

    {
    "converter": {
      "name": "show68_vertical",
      "rawOptions": {
        "rtcChannel": "show68",
        "rtcStreamUid": 201
      },
      "rtmpUrl": "rtmp://example/live/global"
    }
}

    响应示例

    如果状态码为 2XX，则请求成功。示例如下：

    {
    "converter": {
        "id": "4c014467d647bb87b60b719f6fa57686",
        "createTs": 1591786766,
        "updateTs": 1591786766,
        "state": "connecting"
    },
    "fields": "id,createTs,updateTs,state"
}

    Delete: 销毁指定的 Converter

    HTTP 请求

    DELETE https://api.agora.io/{region}/v1/projects/{appId}/rtmp-converters/{converterId}

    路径参数

    • appId: String 型必填参数。Agora 为每个开发者提供的 App ID。在 Agora 控制台创建一个项目后即可得到一个 App ID。一个 App ID 是一个项目的唯一标识。
    • converterId: String 型必填参数。Converter 的 ID。
    • region: String 型必填参数。Converter 所在的区域，必须与创建 Converter 设置的 region 一致。

    请求头

    • Authorization: 该字段的值需参考认证说明。

    • X-Request-ID: UUID（通用唯一识别码），标识本次请求。Agora 服务器会自动生成一个 UUID，并在响应 header 中返回 X-Request-ID 字段。

      Agora 推荐你对 X-Request-ID 赋值，Agora 服务器会在响应 header 中返回一个 X-Custom-Request-ID 字段，以用于问题排查。

    HTTP 响应

    所有可能的响应状态码详见状态码汇总表。

    响应头

    • X-Request-ID：UUID（通用唯一识别码），标识本次请求。该值为本次请求 header 中 X-Request-ID。如果请求出错，请在日志中打印出该值，排查问题。

      如果本次请求的响应状态码不是 2XX，那么响应 header 中可能无该字段。

    • X-Resource-ID：UUID（通用唯一识别码），标识本次请求删除的 Converter 的 ID。

    响应包体

    • 如果状态码为 2XX，则请求成功。Body 为空。
    • 如果状态码不为 2XX，请求失败。Body 中包含 String 类型的 message 字段，描述失败的具体原因。

    Update：更新指定的 Converter

    HTTP 请求

    PATCH https://api.agora.io/{region}/v1/projects/{appId}/rtmp-converters/{converterId}

    路径参数

    • appId: String 型必填参数。Agora 为每个开发者提供的 App ID。在 Agora 控制台创建一个项目后即可得到一个 App ID。一个 App ID 是一个项目的唯一标识。
    • converterId: String 型必填参数。Converter 的 ID。
    • region: String 型必填参数。Converter 所在的区域，必须与创建 Converter 设置的 region 一致。

    查询参数

    sequence：Number 型必填参数。Update 请求的序列号。取值需要大于或等于 0。请确保后一次 Update 请求的序列号大于前一次 Update 请求的序列号。序列号可以确保 Agora 服务器按照你指定的最新配置来更新 Converter。

    Agora 推荐你在第一次调用 Update 时，将 sequence 填 0。在第二次调用 Update 时，将 sequence 填 1。在第三次调用 Update 时，将 sequence 填 2。依次类推。Agora 服务器会按照最新 Update 请求（即最大的序列号）更新 Converter。

    PATCH https://api.agora.io/{region}/v1/projects/{appId}/rtmp-converters/{converterId}?sequence={sequence}

    请求头

    • Content-Type: application/json

    • Authorization: 该字段的值需参考认证说明。

    • X-Request-ID: UUID（通用唯一识别码），标识本次请求。Agora 服务器会自动生成一个 UUID，并在响应 header 中返回 X-Request-ID 字段。

      Agora 推荐你对 X-Request-ID 赋值，Agora 服务器会在响应 header 中返回一个 X-Custom-Request-ID 字段，以用于问题排查。

    请求包体

    你可以同时更新多个字段，字段含义详见 Create 请求 body。

    Update 方法不支持更新 Converter 的如下配置：

    • name

    • idleTimeOut

    • transcodeOptions.rtcChannel

    • transcodeOptions.audioOptions

    • transcodeOptions.audioOptions.codecProfile

    • transcodeOptions.audioOptions.sampleRate

    • transcodeOptions.audioOptions.bitrate

    • transcodeOptions.audioOptions.audioChannels

    • transcodeOptions.videoOptions.codec

    • transcodeOptions.videoOptions.codecProfile

      调用 Create 方法创建一个只输出纯视频/音频流的 Converter 后，你无法通过 Update 方法将其更新为只输出纯音频/视频流的 Converter。

    HTTP 响应

    所有可能的响应状态码详见状态码汇总表。

    响应头

    • X-Request-ID：UUID（通用唯一识别码），标识本次请求。该值为本次请求 header 中 X-Request-ID。如果请求出错，请在日志中打印出该值，排查问题。

      如果本次请求的响应状态码不是 2XX，那么响应 header 中可能无该字段。

    • X-Resource-ID：UUID（通用唯一识别码），标识本次请求更新的 Converter 的 ID。

    响应包体

    如果状态码为 2XX，则请求成功。响应包体中包含字段结构如图所示：

    字段含义详见下表：

    字段 类型 描述               
    converter.id String Converter 的 ID。它是 Agora 服务器生成的一个 UUID（通用唯一识别码），标识一个已创建的 Converter。
    converter.createTs Number 创建 Converter 时的 Unix 时间戳（秒）。
    converter.updateTs Number 最近一次更新 Converter 配置时的 Unix 时间戳（秒）。
    converter.state String Converter 的运行状态：
  • idle: 推流未开始或已结束。
  • connecting: 正在连接 Agora 推流服务器和 CDN 服务器。
  • running: 正在进行推流。
  • failed: 推流失败。
    		•
    fields String JSON 编码方式的字段掩码，详见谷歌 protobuf FieldMask 文档。用于描述返回的 converter 中包含的字段集合。在本示例中，fields 指定了 Agora 服务器返回 converter 字段中的 id，createTs，updateTs 和 state 字段子集。

    如果状态码不为 2XX，请求失败。Body 中包含 String 类型的 message 字段，描述失败的具体原因。

    请求示例

    更新多个字段

    更新 transcodeOptions.videoOptions.canvas 和 converter.transcodeOptions.videoOptions.layout 的示例代码如下：

    {
    "converter": {
        "transcodeOptions": {
            "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/host_placeholder.jpg"
                    }
                ]
            }
        }
    },
    "fields": "transcodeOptions.videoOptions.canvas,transcodeOptions.videoOptions.layout"
}

    调整混音用户的音量大小

    {
  "converter": {
    "transcodeOptions": {
      "audioOptions": {
        "volumes": [
          {
            "volume": 50,
            "rtcStreamUid": 201
          },
          {
            "volume": 150,
            "rtcStreamUid": 201
          }
        ]
      }
    }
  },
  "fields": "transcodeOptions.audioOptions.volumes"
}

    重置混音用户的音量大小

    重置指定用户的音量大小，将其设为默认值：

    {
  "converter": {
    "transcodeOptions": {
      "audioOptions": {
              # 或不设置 volumes
        "volumes": null
      }
    }
  },
  "fields": "transcodeOptions.audioOptions.volumes"
}

    响应示例

    如果状态码为 2XX，则请求成功。示例代码如下：

    {
    "converter": {
      "id": "4c014467d647bb87b60b719f6fa57686",
      "createTs": 1591786766,
      "updateTs": 1591788746,
      "state": "running"
   },
    "fields": "id,createTs,updateTs,state"
}

    Get: 获取指定 Converter 的推流状态

    HTTP 请求

    GET https://api.agora.io/{region}/v1/projects/{appId}/rtmp-converters/{converterId}

    路径参数

    • appId: String 型必填参数。Agora 为每个开发者提供的 App ID。在 Agora 控制台创建一个项目后即可得到一个 App ID。一个 App ID 是一个项目的唯一标识。
    • converterId: String 型必填参数。Converter 的 ID。
    • region: String 型必填参数。Converter 所在的区域，必须与创建 Converter 设置的 region 一致。

    请求头

    • Content-Type: application/json

    • Authorization: 该字段的值需参考认证说明。

    • X-Request-ID: UUID（通用唯一识别码），标识本次请求。Agora 服务器会自动生成一个 UUID，并在响应 header 中返回 X-Request-ID 字段。

      Agora 推荐你对 X-Request-ID 赋值，Agora 服务器会在响应 header 中返回一个 X-Custom-Request-ID 字段，以用于问题排查。

    HTTP 响应

    所有可能的响应状态码详见状态码汇总表。

    响应头

    • X-Request-ID：UUID（通用唯一识别码），标识本次请求。该值为本次请求 header 中 X-Request-ID。如果请求出错，请在日志中打印出该值，排查问题。

      如果本次请求的响应状态码不是 2XX，那么响应 header 中可能无该字段。

    • X-Resource-ID：UUID（通用唯一识别码），标识本次请求更新的 Converter 的 ID。

    响应包体

    转码推流

    如果状态码为 2XX，则请求成功。转码推流响应包体中包含字段结构如图所示：

    字段含义详见下表：

    字段 类型 描述               
    name String Converter 的名字。
    transcodeOptions JSON Object Converter 的转码配置。
    transcodeOptions.rtcChannel String Agora 频道名称。
    transcodeOptions.audioOptions JSON Object Converter 的音频转码配置。详见 audioOptions。
    transcodeOptions.videoOptions JSON Object Converter 的视频转码配置。
    transcodeOptions.videoOptions.canvas JSON Object 视频画布。详见 canvas。
    transcodeOptions.videoOptions.layout JSON Array 画布上视频画面的内容描述。支持 RtcStreamView 和 ImageView 两种元素：
  • RtcStreamView 元素：画布上各用户的视频画面。
  • ImageView 元素：画布上的视频图片，可用于当水印。详见 layout。
    		•
    transcodeOptions.videoOptions.layoutType Number 输出视频的画面布局类型：
  • 0 或（默认）空：自定义布局，即通过 transcodeOptions.videoOptions.layout 设置布局信息。
  • 1：垂直布局。指定一个用户在屏幕左侧显示大视窗画面，其他用户以小视窗画面在屏幕右侧垂直排列，详见设置垂直布局。
    		•
    transcodeOptions.videoOptions.vertical JSON Object 垂直布局的画面设置信息。当 layoutType 为 1 时该参数必定存在。详见 vertical。
    transcodeOptions.videoOptions.
    defaultPlaceholderImageUrl    		 String 默认的用户画面背景图 URL 地址。支持 JPG、PNG 和 GIF 格式的图片。当频道内用户停止发布视频流：
  • 如果设置了该字段，用户的视频画面将切换为该背景图。
  • 如果未设置该字段，用户的视频画面先显示为该用户视频最后一帧，布局刷新后显示为画布背景色。
    		•
    transcodeOptions.videoOptions.bitrate Number 输出视频的编码码率 (Kbps)。
    transcodeOptions.videoOptions.frameRate Number 输出视频的编码帧率 (fps)。
    transcodeOptions.videoOptions.
    codec    		 String 输出视频的编解码规格。支持如下值：
  • H.264（默认值）
  • H.265
    		•
    transcodeOptions.videoOptions.
    codecProfile    		 String 输出视频的编码规格。支持如下值：
  • high（默认值）: High 级别的视频编码规格，一般用于广播及视频碟片存储，高清电视。
  • baseline: Baseline 级别的视频编码规格，一般用于低阶或需要额外容错的应用，比如视频通话、手机视频等。
  • main: Main 级别的视频编码规格，一般用于主流消费类电子产品，如 mp4、便携的视频播放器、PSP 和 iPad 等。
    • 如果 codec 设置为 H.265，则 codecProfile 默认且必须为 main。
    transcodeOptions.videoOptions.seiOptions String 输出视频中携带的用户 SEI 信息。用于向 CDN 发送用户自定义的 SEI 信息。详见 seiOptions。
    rtmpUrl String CDN 推流地址。
    idleTimeout Number Converter 处于空闲状态的最大时长（秒）。空闲指 Converter 处理的音视频流所对应的所有用户均已离开频道。当 Converter 处于空闲状态时长大于 idleTimeout，Converter 自动销毁，推流停止。
    createTs Number 创建 Converter 时的 Unix 时间戳（秒）。
    updateTs Number 最近一次更新 Converter 配置时的 Unix 时间戳（秒）。
    state String Converter 的运行状态：
  • connecting: 正在连接 Agora 推流服务器和 CDN 服务器。
  • running: 正在进行推流。
  • failed: 推流失败。
    		•

    如果状态码不为 2XX，请求失败。Body 中包含 String 类型的 reason 字段，描述失败的具体原因。示例如下：

    {
   "reason": "Resource is not found and destroyed."
}

    不转码推流

    如果状态码为 2XX，请求成功。不转码推流响应包体中包含字段结构如图所示：

    字段含义详见下表：

    字段 类型 描述               
    name String Converter 的名字。
    rawOptions JSON Object Converter 的推流配置。
    rawOptions.rtcChannel String Agora 频道名称。即 Converter 处理的流所属的频道。
    rawOptions.rtcStreamUid Number 要推送的音视频流所属用户的 UID。
    rtmpUrl String CDN 推流的地址。
    idleTimeout Number Converter 处于空闲状态的最大时长（秒）。空闲指 Converter 处理的音视频流所对应的所有用户均已离开频道。当 Converter 处于空闲状态时长大于 idleTimeout，Converter 自动销毁，推流停止。

    如果状态码不为 2XX，请求失败。Body 中包含 String 类型的 reason 字段，描述失败的具体原因。示例如下：

    {
   "reason": "Resource is not found and destroyed."
}

    响应示例

    如果状态码为 2XX，请求成功。示例代码如下：

    转码推流且自定义布局

    {
    "name": "show68_vertical",
    "transcodeOptions": {
        "rtcChannel": "show68",
        "audioOptions": {
            "codecProfile": "HE-AAC",
            "sampleRate": 48000,
            "bitrate": 128,
            "audioChannels": 1,
            "rtcStreamUids": [
                201
            ]
        },
        "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": {}
        }
    },
    "rtmpUrl": "rtmp://example.agora.io/live/show68",
    "idleTimeout": 300,
    "createTs": 1616946970,
    "updateTs": 1783656785,
    "state": "running"
}

    转码推流且垂直布局

    {
    "name": "show68_vertical",
    "transcodeOptions": {
        "rtcChannel": "show68",
        "audioOptions": {
            "codecProfile": "HE-AAC",
            "sampleRate": 48000,
            "bitrate": 128,
            "audioChannels": 1,
            "rtcStreamUids": [
                201
            ]
        },
        "videoOptions": {
            "canvas": {
                "width": 360,
                "height": 640,
                "color": 0
            },
            "layout": [
                {
                    "rtcStreamUid": 201,
                    "region": {
                        "xPos": 0,
                        "yPos": 0,
                        "zIndex": 1,
                        "width": 360,
                        "height": 640
                    },
                    "fillMode": "fill",
                    "placeholderImageUrl": "http://example.agora.io/host_placeholder.jpg"
                }
            ],
            "codec": "H.264",
            "codecProfile": "high",
            "frameRate": 15,
            "gop": 30,
            "bitrate": 400,
            "layoutType": 1,
            "vertical": {
                "maxResolutionUid": 201,
                "fillMode": "fill",
                "refreshIntervalSec": 4
            },
            "defaultPlaceholderImageUrl": "http://example.agora.io/host_placeholder.jpg",
            "seiOptions": {
                "source": {
                    "metadata": true,
                    "datastream": true,
                    "customized": {
                        "payload": "example"
                    }
                },
                "sink": {
                    "type": 100
                }
            }
        }
    },
    "rtmpUrl": "rtmp://example.agora.io/live/show68",
    "idleTimeout": 300
}

    不转码推流

    {
    "converter": {
      "name": "wX8210Ce1VWVyGVHyaHA0W",
      "rawOptions": {
        "rtcChannel": "example",
        "rtcStreamUid": XXXX
      },
      "rtmpUrl": "rtmp://vid-218.push.chinanetcenter.broadcastapp.agora.io/live/global",
      "idleTimeout": 120
    }
}

    List：查询一个项目下所有或指定频道的 Converter

    HTTP 请求

    • 查询一个项目下所有 Converter：GET https://api.agora.io/v1/projects/{appId}/rtmp-converters
    • 查询一个项目下指定频道的 Converter：GET https://api.agora.io/v1/projects/{appId}/channels/{cname}/rtmp-converters

    路径参数

    • appId: String 型必填参数。Agora 为每个开发者提供的 App ID。在 Agora 控制台创建一个项目后即可得到一个 App ID。一个 App ID 是一个项目的唯一标识。
    • cname：String 型必填参数。Agora 频道名称。即 Converter 处理的流所属的频道。字符串长度必须在 64 字节以内，支持以下字符集（共 89 个字符）：
      • 所有小写英文字母（a-z）
      • 所有大写英文字母（A-Z）
      • 数字 0-9
      • 空格
      • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","

    查询参数

    cursor：Number 型参数。游标，用于分页查询 Converter 信息列表。取值必须大于或等于 0。

    • 首次发起查询请求时无需设置 cursor，请求成功后返回第一页 Converter 列表。
    • 每次查询最多返回 500 个 Converter 的相关信息，如果项目下 Converter 数量超过 500，从响应 body 中获取 cursor，并在下一次请求的 URL 中传入该 cursor，直到响应 body 中 cursor 字段值为 0，则表示已查询到项目下或指定频道的所有 Converter。

    使用 Query Parameters 的 HTTP URL 如下：

    • 查询一个项目下所有 Converter：GET https://api.agora.io/v1/projects/{appId}/rtmp-converters?cursor={cursor}
    • 查询一个项目下指定频道的 Converter：GET https://api.agora.io/v1/projects/{appId}/channels/{cname}/rtmp-converters?cursor={cursor}

    请求头

    • Content-Type: application/json

    • Authorization: 该字段的值需参考认证说明。

    • X-Request-ID: UUID（通用唯一识别码），标识本次请求。Agora 服务器会自动生成一个 UUID，并在响应 header 中返回 X-Request-ID 字段。

      Agora 推荐你对 X-Request-ID 赋值，Agora 服务器会在响应 header 中返回一个 X-Custom-Request-ID 字段，以用于问题排查。

    HTTP 响应

    所有可能的响应状态码详见状态码汇总表。

    响应头

    X-Request-ID：UUID（通用唯一识别码），标识本次请求。该值为本次请求 header 中 X-Request-ID。如果请求出错，请在日志中打印出该值，排查问题。

    如果本次请求的响应状态码不是 2XX，那么响应 header 中可能无该字段。

    响应包体

    如果状态码为 2XX，则请求成功。响应包体中包含字段结构如图所示：

    字段含义详见下表：

    字段 类型 描述
    success Bool 请求成功。
    data JSON Object 返回数据详情。
    data.total_count String 所查项目或频道下所有 Converter 的数量。
    data.cursor JSON 游标，用于分页查询 Converter 信息列表。cursor为 0 表示已查询到项目下或指定频道的所有 Converter；否则需要继续查询。
    data.members.rtcChannel String Agora 频道名称。即 Converter 处理的流所属的频道。
    data.members.converterName String Converter 名称。
    data.members.updateTs Number 最近一次更新 Converter 配置时的 Unix 时间戳（秒）。
    data.members.appId String Agora 为每个开发者提供的 App ID。在 Agora 控制台创建一个项目后即可得到一个 App ID。一个 App ID 是一个项目的唯一标识。
    data.members.rtmpUrl String CDN 推流地址。
    data.members.converterId String Converter 的 ID。Converter 的唯一标识。
    data.members.create Number 创建 Converter 时的 Unix 时间戳（秒）。
    data.members.idleTimeout Number Converter 处于空闲状态的最大时长（秒）。空闲指 Converter 处理的音视频流所对应的所有用户均已离开频道。当 Converter 处于空闲状态时长大于 idleTimeout，Converter 自动销毁，推流停止。
    data.members.state String Converter 的运行状态：
  • idle: 推流未开始或已结束。
  • connecting: 正在连接 Agora 推流服务器和 CDN 服务器。
  • running: 正在进行推流。
  • failed: 推流失败。
    		•

    响应示例

    如果状态码为 2XX，则请求成功。示例代码如下： 

    {
    "success": true,
    "data": {
        "total_count": 1,
        "cursor": 0,
        "members": [
            {
                "rtcChannel": "testchannel",
                "status": "200",
                "converterName": "wX821XXXXVWVyGVHyaHA0W",
                "updateTs": "1641267823",
                "appId": "aab8b8f5aXXXX469a63042fcfafe7063",
                "rtmpUrl": "rtmp://example/live/areu",
                "ip": "183.131.160.244",
                "converterId": "889B6D4BXXXXB62E68CCDA978BF21350",
                "create": "1641267818",
                "idleTimeout": "120",
                "state": "running"
            }
        ]
    }
}

    注意事项

    本节总结使用推流 RESTful API 的重要注意事项。

    注意事项                                          影响程度
    请确保 Agora 频道场景为直播。 ★★★☆☆
    如果你需要同一个频道内仅有一个 Converter，请你务必使用 name 参数，详见 name 参数解释。 ★★★☆☆
    请确保将 region 设置为 CDN 源站所在区域，详见 region 参数解释。 ★★★★★
    如果 Converter 因为服务故障等原因自动销毁，Agora 推荐你重新创建一个 Converter。 ★★★★★
    创建 Converter 后，如果 CDN 侧拉流异常。Agora 推荐你 Delete 该 Converter，再重新创建一个 Converter。 ★★★★★
    不支持在一个 Converter 内转换转码推流和不转码推流。如要使用另一种方式的推流，你需要重新创建一个 Converter 并进行相关配置。 ★★★☆☆
    请确保对同一个 Converter 进行多次 Update 时，sequence 值递增，详见 sequence 参数解释。 ★★★★★
    请求出错时，请务必在日志中打印出响应 Header 中的 X-Request-ID 和 X-Resource-ID 字段值，以方便排查问题。 ★★★☆☆

    参考信息

    API 限流说明

    Agora 服务器限制用户 API 调用速率，超出限制速率时会返回状态码 429(Too Many Requests)。如果你有更高调用速率需求，请联系技术支持。

    API       限流说明
    Create 一个项目中，创建 Converter 的速率上限为 50 次/秒。
    Delete 一个项目中，销毁 Converter 的速率上限为 50 次/秒。
    Update 一个项目中，更新一个指定的 Converter 的速率上限为 50 次/秒。
    Get 一个项目中，更新一个指定的 Converter 的速率上限为 50 次/秒。

    状态码汇总表

    • 如果状态码为 2XX，则请求成功。
    • 如果状态码不为 2XX，则请求失败。请根据对应的响应报文 Body 中的 message 字段内容排查问题。
    状态码          可能的 message 字段内容
    200 OK /
    400 Bad Request
  • Invalid parameter: rtmpUrl. Replace it and retry.
  • Invalid parameter: idleTimeout. Replace it and retry.
    		•
    401 Unauthorized Invalid authentication credentials.
    403 Forbidden No valid permission to use this function. Contact us.
    404 Not Found Resource is not found and destroyed.
    409 Conflict Resource with the same name has already existed. Use the existing resource, otherwise delete it and create a new resource.
    429 Too Many Requests
  • Request rate limit exceeded.
  • Resource quota limit exceeded.
  • No available resources.
    		•
    500 Unknown Internal errors. Contact us for troubleshooting.
    501 Not Implemented The method requested has not been implemented.
    503 Service Unavailable
  • The server is temporarily overloading. Retry with a backoff strategy and contact us for troubleshooting.
  • The server is temporarily down. Retry with a backoff strategy.
    		•
    504 Gateway Timeout Gateway timeout. Check whether the resource is created, if not, re-create a new resource.

    常用视频属性

    设置转码输出媒体流的视频分辨率、帧率和码率时，Agora 推荐你使用默认值。你也可以参考下表设值。如果设置的码率超出合理范围，Agora 服务器会在合理区间内自动调整码率。

    分辨率 帧率 (fps) 码率 (Kbps)
    160 × 120 15 130
    120 × 120 15 100
    320 × 180 15 280
    180 × 180 15 200
    240 × 180 15 240
    320 × 240 15 400
    240 × 240 15 280
    424 × 240 15 440
    640 × 360 15 800
    360 × 360 15 520
    640 × 360 30 1200
    360 × 360 30 800
    480 × 360 15 640
    480 × 360 30 980
    640 × 480 15 1000
    480 × 480 15 800
    640 × 480 30 1500
    480 × 480 30 1200
    848 × 480 15 1220
    848 × 480 30 1860
    640 × 480 10 800
    1280 × 720 15 2260
    1280 × 720 30 3420
    960 × 720 15 1820
    960 × 720 30 2760