文档中心
互动直播
Agora.io 社区
中文
search-icon
推流到 CDN RESTful API
更新时间 2021/10/12 09:02:39

你可以使用推流 RESTful API 将 Agora 频道内的音视频流由 Agora 私有协议转换为标准协议（如 RTMP），然后推到 CDN（Content Delivery Network）。这个过程相当于 Agora 通过一个 Converter 将音视频流处理后输出并推到 CDN。

开通服务

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

  1. 提交工单联系声网技术支持开通 RTMP Converter 服务。
  2. 登录控制台，点击左侧导航栏 img 按钮进入产品用量页面。
  3. 在页面左上角展开下拉列表选择需要开通云端录制的项目，然后点击云端录制下的分钟数。
  4. 点击开启 RTMP 推流服务。
  5. 点击应用。

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

通过 Basic HTTP 认证

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

工作原理

你可以通过如下方法控制 Converter：

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

在推流 RESTful API 中，Converter 通过 converter 字段设置，字段结构如图所示：

字段含义详见下表：

字段 类型 描述               
id String Converter 的 ID。它是 Agora 服务器生成的一个 UUID（通用唯一识别码），标识一个已创建的 Converter。
name String，可选 Converter 的名字。
transcodeOptions JSON Object Converter 的转码配置。
transcodeOptions.rtcChannel String Agora 频道名称。
transcodeOptions.audioOptions JSON Object Converter 的音频转码配置。
transcodeOptions.audioOptions.codecProfile String Converter 输出的音频编解码器。
transcodeOptions.audioOptions.sampleRate Number Converter 输出的音频编码采样率 (Hz)。
transcodeOptions.audioOptions.bitrate Number Converter 输出的音频编码码率 (Kbps)。
transcodeOptions.audioOptions.audioChannels Number Converter 输出的音频声道数。
transcodeOptions.audioOptions.rtcStreamUids JSON Array 参与混音的用户 UID/Account。
transcodeOptions.videoOptions JSON Object Converter 的视频转码配置。
transcodeOptions.videoOptions.canvas JSON Object 视频画布。
transcodeOptions.videoOptions.canvas.width Number 画布的宽度 (pixel)。
transcodeOptions.videoOptions.canvas.height Number 画布的高度 (pixel)。
transcodeOptions.videoOptions.canvas.color Number 画布的背景色。RGB 颜色值，以十进制数表示。如 255 代表蓝色。
transcodeOptions.videoOptions.layout JSON Array 画布上视频画面的内容描述。支持 RtcStreamView 和 ImageView 两种元素。
transcodeOptions.videoOptions.
layout.RtcStreamView 元素		 无 画布上各用户的视频画面。
transcodeOptions.videoOptions.
layout.RtcStreamView 元素.rtcStreamUid		 Number 视频流所属用户的 UID。
transcodeOptions.videoOptions.
layout.RtcStreamView 元素.rtcStreamAccount		 String 视频流所属用户的 Account。
transcodeOptions.videoOptions.
layout.RtcStreamView 元素.region		 JSON Object 用户视频画面在画布上的显示区域。
transcodeOptions.videoOptions.
layout.RtcStreamView 元素.region.xPos		 Number 画面在画布上的 x 坐标 (pixel)。以画布左上角为原点，x 坐标为画面左上角相对于原点的横向位移。
transcodeOptions.videoOptions.
layout.RtcStreamView 元素.region.yPos		 Number 画面在画布上的 y 坐标 (pixel)。以画布左上角为原点，y 坐标为画面左上角相对于原点的纵向位移。
transcodeOptions.videoOptions.
layout.RtcStreamView 元素.region.zIndex		 Number 画面的图层编号。取值范围为 [0,100]。0 代表最下层的图层。100 代表最上层的图层。
transcodeOptions.videoOptions.
layout.RtcStreamView 元素.region.width		 Number 画面的宽度 (pixel)。
transcodeOptions.videoOptions.
layout.RtcStreamView 元素.region.height		 Number 画面的高度 (pixel)。
transcodeOptions.videoOptions.
layout.RtcStreamView 元素.fillMode		 String 画面的显示方式。
  • fill：在保持长宽比的前提下，缩放画面，使画面充满容器。
  • fit：在保持长宽比的前提下，缩放画面，使得画面在容器内完整显示出来。
    • transcodeOptions.videoOptions.
    layout.RtcStreamView 元素.placeholderImageUrl    		 String 替代图片的 HTTP(s) URL。
    transcodeOptions.videoOptions.
    layout.ImageView 元素    		 无 画布上的视频图片，可当水印。
    transcodeOptions.videoOptions.
    layout.ImageView 元素.imageUrl    		 String 图片的 HTTP(S) URL。
    transcodeOptions.videoOptions.
    layout.ImageView 元素.region    		 JSON Object 图片在画布上的显示区域。
    transcodeOptions.videoOptions.
    layout.ImageView 元素.region.xPos    		 Number 图片在画布上的 x 坐标 (pixel)。以画布左上角为原点，x 坐标为图片左上角相对于原点的横向位移。
    transcodeOptions.videoOptions.
    layout.ImageView 元素.region.yPos    		 Number 图片在画布上的 y 坐标 (pixel)。以画布左上角为原点，y 坐标为图片左上角相对于原点的纵向位移。
    transcodeOptions.videoOptions.
    layout.ImageView 元素.region.zIndex    		 Number 图片的图层编号。取值范围为 [0,100]。0 代表最下层的图层。100 代表最上层的图层。
    transcodeOptions.videoOptions.
    layout.ImageView 元素.region.width    		 Number 图片的宽度 (pixel)。
    transcodeOptions.videoOptions.
    layout.ImageView 元素.region.height    		 Number 图片的高度 (pixel)。
    transcodeOptions.videoOptions.
    layout.ImageView 元素.fillMode    		 String 图片的显示方式。
  • fill：在保持长宽比的前提下，缩放图片，使图片充满容器。
  • fit：在保持长宽比的前提下，缩放图片，使得图片在容器内完整显示出来。
    • transcodeOptions.videoOptions.bitrate Number 输出视频的编码码率 (Kbps)。
    transcodeOptions.videoOptions.frameRate Number 输出视频的编码帧率 (fps)。
    transcodeOptions.videoOptions.gop Number 输出视频的 GOP。
    transcodeOptions.videoOptions.codecProfile String 输出视频的编码规格。
    transcodeOptions.videoOptions.seiOptions JSON Object 设置输出视频中携带的用户 SEI 信息。默认为空。不设置则表示不输出 SEI 信息。
    transcodeOptions.videoOptions.
    seiOptions.source    		 JSON Object 设置 SEI 信息的数据来源。默认为空。
    transcodeOptions.videoOptions.
    seiOptions.source.metadata    		 Bool 设置是否传入 metadata 类型的 SEI 信息。
  • true：传入 metadata 类型的 SEI 信息。
  • （默认）false：不传入 metadata 类型的 SEI 信息。
    		•
    transcodeOptions.videoOptions.
    seiOptions.source.datastream    		 Bool 设置是否传入 Agora DataStream 类型的 SEI 信息 。
  • true：传入 Agora DataStream 类型的 SEI 信息。
  • （默认）false：不传入 Agora DataStream 类型的 SEI 信息。
    		•
    transcodeOptions.videoOptions.
    seiOptions.source.customized    		 JSON Object 自定义 SEI 信息。该 SEI 信息会被转换为声网 SEI 规范的 SEI 信息。默认为空。
    transcodeOptions.videoOptions.
    seiOptions.source.customized.prefixForAgoraSei    		 String 设置 SEI 信息的 payload 前缀。长度必须在 32 个字符以内，默认为空。
    transcodeOptions.videoOptions.
    seiOptions.source.customized.payload    		 String 设置 SEI 信息的 payload。默认为空。SEI 信息被转换为声网 SEI 规范的 SEI 信息时，该 payload 会被传入到 SEI 的 app_data 中。
    transcodeOptions.videoOptions.
    seiOptions.sink    		 JSON Object 设置输出 SEI 信息的属性。默认为空。
    transcodeOptions.videoOptions.
    seiOptions.sink.type    		 Int 设置输出 SEI 信息的 payload type。默认为 100。
    rtmpUrl String CDN 推流地址。
    idleTimeout Number Converter 处于空闲状态的最大时长（秒）。空闲指 Converter 处理的音视频流所对应的所有用户均已离开频道。取值范围为 [5,600]。默认值为 300。取值超出范围会报错。
    createTs Number 创建 Converter 时的 Unix 时间戳（秒）。
    updateTs Number 最近一次更新 Converter 配置时的 Unix 时间戳（秒）。
    state String Converter 的运行状态：
  • idle: 推流未开始或已结束。
  • connecting: 正在连接 Agora 推流服务器和 CDN 服务器。
  • running: 正在进行推流。
  • failed: 推流失败。
    		•

    一个完整的 Converter 示例如下：

    {
    "id": "4c014467d647bb87b60b719f6fa57686",
    "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"
                }
            ],
            "codecProfile": "high",
            "frameRate": 15,
            "gop": 30,
            "bitrate": 400,
            "seiOptions": {
                "source": {
                    "metadata": true,
                    "datastream": true,
                    "customized": {
                        "payload": "example"
                    }
                },
                "sink": {
                    "type": 100
                }
            }
        }
    },
    "rtmpUrl": "rtmp://example.agora.io/live/show68",
    "idleTimeout": 300,
    "createTs": 1591786766,
    "updateTs": 1591786835,
    "state": "connecting"
}

    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 的值为小写。

    • Query Parameters

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

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

    请求报文的 Header 字段

    • 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 字段，以用于问题排查。

    请求报文的 Body

    该示例展示将 show68 频道内指定的两个用户合图后推到 CDN，并且频道内所有用户音频进行混音。

    示例代码

    {
    "converter": {
        "name": "show68_vertical",
        "transcodeOptions": {
            "rtcChannel": "show68",
            "audioOptions": {
                "codecProfile": "LC-AAC",
                "sampleRate": 48000,
                "bitrate": 48,
                "audioChannels": 1
            },
            "videoOptions": {
                "canvas": {
                    "width": 360,
                    "height": 640
                },
                "layout": [
                    {
                        "rtcStreamUid": 201,
                        "region": {
                            "xPos": 0,
                            "yPos": 0,
                            "zIndex": 1,
                            "width": 360,
                            "height": 320
                        },
                        "fillMode": "fill",
                        "placeholderImageUrl": "http://example.agora.io/user_placeholder.jpg"
                    },
                    {
                        "rtcStreamUid": 202,
                        "region": {
                            "xPos": 0,
                            "yPos": 320,
                            "zIndex": 1,
                            "width": 360,
                            "height": 320
                        }
                    }
                ],
                "codecProfile": "High",
                "frameRate": 15,
                "gop": 30,
                "bitrate": 400,
                "seiOptions": {}
            }
        },
        "rtmpUrl": "rtmp://example.agora.io/live/show68"
    }
}

    设置 SEI 信息（seiOptions）示例代码如下：

    {
    "converter": {
        "transcodeOptions": {
            "videoOptions": {
                "seiOptions": {
                    "source": {
                        "metadata": true,
                        "datastream": true,
                        "customized": {
                            "payload": "example"
                        }
                    },
                    "sink": {
                        "type": 100
                    }
                }
            }
        }
    }
}

    请求 Body 为 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 的转码配置。
  • 当 converter.transcodeOptions 中无 audioOptions 字段且有 videoOptions 字段时，Converter 输出纯视频流。
  • 当 converter.transcodeOptions.audioOptions 字段中无 rtcStreamUids 字段时，Agora 会将频道内所有用户的音频流进行混音并通过 Converter 输出混音后的音频流。
  • 当 converter.transcodeOptions.audioOptions 字段中有 rtcStreamUids 字段时，Agora 会将指定用户的音频流进行混音并通过 Converter 输出混音后的音频流。
    		•
    transcodeOptions.rtcChannel String（必填） Agora 频道名称。即 Converter 处理的流所属的频道。字符串长度必须在 64 字节以内，支持以下字符集（共 89 个字符）：
  • 所有小写英文字母（a-z）
  • 所有大写英文字母（A-Z）
  • 数字 0-9
  • 空格
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    		•
    transcodeOptions.audioOptions JSON Object Converter 的音频转码配置。
  • 在纯视频流（无音频）场景中，无需设置 audioOptions 及其相关字段。
  • 在音视频场景中，audioOptions 为必填字段，若无字段要求，可以把 audioOptions 设置为空，例如："audioOptions":{}
    • transcodeOptions.audioOptions.
    codecProfile    		 String（可选） Converter 输出的音频编解码器。支持如下值：
  • LC-AAC（默认值）: MPEG-4 AAC LC。
  • HE-AAC: High-Efficiency AAC。
    		•
    transcodeOptions.audioOptions.
    sampleRate    		 Number（可选） Converter 输出的音频编码采样率 (Hz)，可填 32000，44100 或 48000（默认值）。
    transcodeOptions.audioOptions.
    bitrate    		 Number（可选） Converter 输出的音频编码码率 (Kbps)取值范围为 [32,128]。默认值为 48。如果音频编解码器为 LC-AAC，推荐音频编码码率取值范围为 [32, 112]。如果音频编解码器为 HE-AAC，推荐音频编码码率取值范围为 [40, 96]。
    transcodeOptions.audioOptions.
    audioChannels    		 Number（可选） Converter 输出的音频声道数，可填 1（默认值） 或 2。
    transcodeOptions.audioOptions.
    rtcStreamUids    		 JSON Array（可选） 参与混音的用户 UID/Account。默认值为频道内所有用户 UID/Account，代表 Agora 将频道内所有用户音频进行混音。
    transcodeOptions.videoOptions JSON Object（可选） Converter 的视频转码配置。
  • 在纯音频流（无视频）场景中，无需设置 videoOptions 及其相关字段。
  • 在音视频场景中，videoOptions 为必填字段，且不能为空。
    • transcodeOptions.videoOptions.canvas JSON Object（必填） 视频画布。
    transcodeOptions.videoOptions
    .canvas.width    		 Number（必填） 画布的宽度 (pixel)。取值范围为 [66,1920]。
    transcodeOptions.videoOptions.
    canvas.height    		 Number（必填） 画布的高度 (pixel)。取值范围为 [66,1920]。
    transcodeOptions.videoOptions.
    canvas.color    		 Number（可选） 画布的背景色。RGB 颜色值，以十进制数表示。如 255 代表蓝色。取值范围为 [0,16777215]。默认值为 0，即黑色。
    transcodeOptions.videoOptions.layout JSON Array（必填） 画布上视频画面的内容描述。支持 RtcStreamView 和 ImageView 两种元素。
    transcodeOptions.videoOptions.
    layout.RtcStreamView 元素    		 无 画布上各用户的视频画面。
    Agora 支持频道内用户名为 Number 型的 UID 或 String 型的 Account。如果使用 String 型 Account，请确保已经阅读如何使用 String 型用户名。
    transcodeOptions.videoOptions.
    layout.RtcStreamView 元素.rtcStreamUid    		 Number 视频流所属用户的 UID。请在 rtcStreamUid 和 rtcStreamAccount 中选择一个使用。
    transcodeOptions.videoOptions.
    layout.RtcStreamView 元素.rtcStreamAccount    		 String 视频流所属用户的 Account。请在 rtcStreamUid 和 rtcStreamAccount 中选择一个使用。
    transcodeOptions.videoOptions.
    layout.RtcStreamView 元素.region    		 JSON Object（必填） 用户视频画面在画布上的显示区域。超出画布的视频画面会被裁剪，无法显示。
    transcodeOptions.videoOptions.
    layout.RtcStreamView 元素.region.xPos    		 Number（必填） 画面在画布上的 x 坐标 (pixel)。以画布左上角为原点，x 坐标为画面左上角相对于原点的横向位移。
    transcodeOptions.videoOptions.
    layout.RtcStreamView 元素.region.yPos    		 Number（必填） 画面在画布上的 y 坐标 (pixel)。以画布左上角为原点，y 坐标为画面左上角相对于原点的纵向位移。
    transcodeOptions.videoOptions.
    layout.RtcStreamView 元素.region.zIndex    		 Number（必填） 画面的图层编号。取值范围为 [0,100]。0 代表最下层的图层。100 代表最上层的图层。
    transcodeOptions.videoOptions.
    layout.RtcStreamView 元素.region.width    		 Number（必填） 画面的宽度 (pixel)。
    transcodeOptions.videoOptions.
    layout.RtcStreamView 元素.region.height    		 Number（必填） 画面的高度 (pixel)。
    transcodeOptions.videoOptions.
    layout.RtcStreamView 元素.fillMode    		 String（可选） 画面的显示方式。
  • fill：在保持长宽比的前提下，缩放画面，使画面充满容器。
  • fit：在保持长宽比的前提下，缩放画面，使得画面在容器内完整显示出来。
    • transcodeOptions.videoOptions.
    layout.RtcStreamView 元素.placeholderImageUrl    		 String（必填） 替代图片的 HTTP(s) URL。支持 JPG 和 PNG 格式的图片。当频道内用户不发布视频流时，如果设置了该字段，替代图片会替代该用户的视频画面，否则会显示该用户的最后一帧视频。
    transcodeOptions.videoOptions.
    layout.ImageView 元素    		 无 画布上的视频图片，可用于当水印。
    transcodeOptions.videoOptions.
    layout.ImageView 元素.imageUrl    		 String（必填） 图片的 HTTP(S) URL。支持 JPG 和 PNG 格式的图片。
    transcodeOptions.videoOptions.
    layout.ImageView 元素.region    		 JSON Object（必填） 图片在画布上的显示区域。超出画布的图片会被裁剪，无法显示。
    transcodeOptions.videoOptions.
    layout.ImageView 元素.region.xPos    		 Number（必填） 图片在画布上的 x 坐标 (pixel)。以画布左上角为原点，x 坐标为图片左上角相对于原点的横向位移。
    transcodeOptions.videoOptions.
    layout.ImageView 元素.region.yPos    		 Number（必填） 图片在画布上的 y 坐标 (pixel)。以画布左上角为原点，y 坐标为图片左上角相对于原点的纵向位移。
    transcodeOptions.videoOptions.
    layout.ImageView 元素.region.zIndex    		 Number（必填） 图片的图层编号。取值范围为 [0,100]。0 代表最下层的图层。100 代表最上层的图层。
    transcodeOptions.videoOptions.
    layout.ImageView 元素.region.width    		 Number（必填） 图片的宽度 (pixel)。
    transcodeOptions.videoOptions.
    layout.ImageView 元素.region.height    		 Number（必填） 图片的高度 (pixel)。
    transcodeOptions.videoOptions.
    layout.ImageView 元素.fillMode（可选）    		 String 图片的显示方式。
  • fill：在保持长宽比的前提下，缩放图片，使图片充满容器。
  • fit：在保持长宽比的前提下，缩放图片，使得图片在容器内完整显示出来。
    • transcodeOptions.videoOptions.bitrate Number（必填） 输出视频的编码码率 (Kbps)。取值范围为 [1,10000]。详见常用视频属性。
    transcodeOptions.videoOptions.
    frameRate    		 Number（可选） 输出视频的编码帧率 (fps)。取值范围为 [1,30]。默认值为 15。详见常用视频属性。
    transcodeOptions.videoOptions.
    gop    		 Number（可选） 输出视频的 GOP。默认值为 frameRate * 2。
    transcodeOptions.videoOptions.
    codecProfile    		 String（可选） 输出视频的编码规格。输出视频的编码规格。支持如下值：
  • high（默认值）: High 级别的视频编码规格，一般用于广播及视频碟片存储，高清电视。
  • baseline: Baseline 级别的视频编码规格，一般用于低阶或需要额外容错的应用，比如视频通话、手机视频等。
  • main: Main 级别的视频编码规格，一般用于主流消费类电子产品，如 mp4、便携的视频播放器、PSP 和 iPad 等。
    		•
    transcodeOptions.videoOptions.seiOptions JSON Object（可选） 设置输出视频中携带的用户 SEI 信息。默认为空。不设置则表示不输出 SEI 信息。
    transcodeOptions.videoOptions.seiOptions.source JSON Object（可选） 设置 SEI 信息的数据来源。默认为空。
    transcodeOptions.videoOptions.seiOptions.
    source.metadata    		 Bool（可选） 设置是否传入 metadata 类型的 SEI 信息。
  • true：传入 metadata 类型的 SEI 信息。
  • （默认）false：不传入 metadata 类型的 SEI 信息。
    		•
    transcodeOptions.videoOptions.seiOptions.
    source.datastream    		 Bool（可选） 设置是否传入 Agora DataStream 类型的 SEI 信息 。
  • true：传入 Agora DataStream 类型的 SEI 信息。
  • （默认）false：不传入 Agora DataStream 类型的 SEI 信息。
    		•
    transcodeOptions.videoOptions.seiOptions.
    source.customized    		 JSON Object（可选） 自定义 SEI 信息。该 SEI 信息会被转换为声网 SEI 规范的 SEI 信息。默认为空。
    transcodeOptions.videoOptions.seiOptions.
    source.customized.prefixForAgoraSei    		 String（可选） 设置 SEI 信息的 payload 前缀。长度必须在 32 个字符以内，默认为空。
    transcodeOptions.videoOptions.seiOptions.
    source.customized.payload    		 String（可选） 设置 SEI 信息的 payload。长度必须在 4096 个字符以内，默认为空。SEI 信息被转换为声网 SEI 规范的 SEI 信息时，该 payload 会被传入到 SEI 的 app_data 中。
    transcodeOptions.videoOptions.seiOptions.
    sink    		 JSON Object（可选） 设置输出 SEI 信息的属性。默认为空。
    transcodeOptions.videoOptions.seiOptions.
    sink.type    		 Int（可选） 设置输出 SEI 信息的 payload type。默认为 100。
    rtmpUrl String（必填） CDN 推流地址。必须为有效的 RTMP 地址，且长度在 1024 个字符以内。

    HTTP 响应

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

    响应报文的 Header 字段

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

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

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

    响应报文的 Body

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

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

    img

    字段含义详见下表：

    字段 类型 描述               
    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 字段，描述失败的具体原因。

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

    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 一致。

    Query Parameters

    无

    请求报文的 Header 字段

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

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

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

    请求报文的 Body

    空

    HTTP 响应

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

    响应报文的 Header 字段

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

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

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

    响应报文的 Body

    • 如果状态码为 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 一致。

    Query Parameters

    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}

    请求报文的 Header 字段

    • 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 字段，以用于问题排查。

    请求报文的 Body

    • 更新 converter.transcodeOptions.videoOptions.layout 配置。请务必参考如下示例代码：

      {
  "converter": {
      "transcodeOptions": {
          "videoOptions": {
              "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": 703,
                      "region": {
                          "xPos": 0,
                          "yPos": 320,
                          "zIndex": 1,
                          "width": 360,
                          "height": 320
                      },
                      "fillMode": "fit",
                      "placeholderImageUrl": "http://example.agora.io/guest_placehoder.jpg"
                  }
              ]
          }
      }
  },
  "fields": "transcodeOptions.videoOptions.layout"
}

    • 更新 converter.transcodeOptions.audioOptions.rtcStreamUids 配置。请务必参考如下示例代码：

    {
    "converter": {
        "transcodeOptions": {
            "audioOptions": {
                "rtcStreamUids": [
                    201,
                    202
                ]
            }
        },
        "fields": "transcodeOptions.audioOptions.rtcStreamUids"
    }
}

    • 更新 transcodeOptions.videoOptions.seiOptions 配置。请务必参考如下示例代码：

      {
  "converter": {
      "transcodeOptions": {
          "videoOptions": {
              "seiOptions": {
                  "source": {
                      "metadata": true,
                      "datastream": true,
                      "customized": {
                          "payload": "example"
                      }
                  },
                  "sink": {
                      "type": 119
                  }
              }
          }
      }
  },
  "fields": "transcodeOptions.videoOptions.seiOptions"
}
      • 更新 transcodeOptions.videoOptions.seiOptions.source 配置。请务必参考如下示例代码：
        {
"converter": {
    "transcodeOptions": {
        "videoOptions": {
            "seiOptions": {
                "source": {
                    "metadata": true,
                    "datastream": true,
                    "customized": {
                        "payload": "example"
                    }
                }
            }
        }
    }
},
"fields": "transcodeOptions.videoOptions.seiOptions.source"
}

    • 更新 transcodeOptions.videoOptions.seiOptions.sink 配置：

      {
  "converter": {
      "transcodeOptions": {
          "videoOptions": {
              "seiOptions": {
                  "sink": {
                      "type": 119
                  }
              }
          }
      }
  },
  "fields": "transcodeOptions.videoOptions.seiOptions.sink"
}

    • 更新 converter 的其他配置，如 converter.rtmpUrl:

      {
   "converter": {
       "rtmpUrl": "rtmp://example.agora.io/live/show68_backup"
   },
   "fields": "rtmpUrl"
}

    字段含义详见 Create 请求 body。

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

    • name

    • idleTimeOut

    • transcodeOptions.rtcChannel

    • transcodeOptions.audioOptions

    • transcodeOptions.audioOptions.codecProfile

    • transcodeOptions.audioOptions.sampleRate

    • transcodeOptions.audioOptions.bitrate

    • transcodeOptions.audioOptions.audioChannels

    • transcodeOptions.videoOptions.codecProfile

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

    HTTP 响应

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

    响应报文的 Header 字段

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

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

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

    响应报文的 Body

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

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

    img

    字段含义详见下表：

    字段 类型 描述               
    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 字段，描述失败的具体原因。

    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 一致。

    Query Parameters

    无

    请求报文的 Header 字段

    • 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 响应

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

    响应报文的 Header 字段

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

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

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

    响应报文的 Body

    {
    "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"
                }
            ],
            "codecProfile": "High",
            "frameRate": 15,
            "gop": 30,
            "bitrate": 400,
            "seiOptions": {}
        }
    },
    "rtmpUrl": "rtmp://example.agora.io/live/show68",
    "idleTimeout": 300,
    "createTs": 1616946970,
        "updateTs" : 1783656785,
    "state": "running"
}

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

    字段含义详见下表：

    字段 类型 描述               
    name String，可选 Converter 的名字。
    transcodeOptions JSON Object Converter 的转码配置。
    transcodeOptions.rtcChannel String Agora 频道名称。
    transcodeOptions.audioOptions JSON Object Converter 的音频转码配置。
    transcodeOptions.audioOptions.codecProfile String Converter 输出的音频编解码器。
    transcodeOptions.audioOptions.sampleRate Number Converter 输出的音频编码采样率 (Hz)。
    transcodeOptions.audioOptions.bitrate Number Converter 输出的音频编码码率 (Kbps)。
    transcodeOptions.audioOptions.rtcStreamUids JSON Array 参与混音的用户 UID/Account。
    transcodeOptions.videoOptions JSON Object Converter 的视频转码配置。
    transcodeOptions.videoOptions.canvas JSON Object 视频画布。
    transcodeOptions.videoOptions.canvas.width Number 画布的宽度 (pixel)。
    transcodeOptions.videoOptions.canvas.height Number 画布的高度 (pixel)。
    transcodeOptions.videoOptions.canvas.color Number 画布的背景色。RGB 颜色值，以十进制数表示。如 255 代表蓝色。
    transcodeOptions.videoOptions.layout JSON Array 画布上视频画面的内容描述。支持 RtcStreamView 和 ImageView 两种元素。
    transcodeOptions.videoOptions.layout.RtcStreamView 元素 无 画布上各用户的视频画面。
    transcodeOptions.videoOptions.
    layout.RtcStreamView 元素.rtcStreamUid    		 Number 视频流所属用户的 UID。
    transcodeOptions.videoOptions.
    layout.RtcStreamView 元素.region    		 JSON Object 用户视频画面在画布上的显示区域。
    transcodeOptions.videoOptions.
    layout.RtcStreamView 元素.region.xPos    		 Number 画面在画布上的 x 坐标 (pixel)。以画布左上角为原点，x 坐标为画面左上角相对于原点的横向位移。
    transcodeOptions.videoOptions.
    layout.RtcStreamView 元素.region.yPos    		 Number 画面在画布上的 y 坐标 (pixel)。以画布左上角为原点，y 坐标为画面左上角相对于原点的纵向位移。
    transcodeOptions.videoOptions.
    layout.RtcStreamView 元素.region.zIndex    		 Number 画面的图层编号。取值范围为 [0,100]。0 代表最下层的图层。100 代表最上层的图层。
    transcodeOptions.videoOptions
    .layout.RtcStreamView 元素.region.width    		 Number 画面的宽度 (pixel)。
    transcodeOptions.videoOptions.
    layout.RtcStreamView 元素.region.height    		 Number 画面的高度 (pixel)。
    transcodeOptions.videoOptions.
    layout.RtcStreamView 元素.fillMode    		 String 画面的显示方式。
  • fill：在保持长宽比的前提下，缩放画面，使画面充满容器。
  • fit：在保持长宽比的前提下，缩放画面，使得画面在容器内完整显示出来。
    • transcodeOptions.videoOptions.
    layout.RtcStreamView 元素.placeholderImageUrl    		 String 替代图片的 HTTP(s) URL。
    transcodeOptions.videoOptions.layout.ImageView 元素 无 画布上的视频图片，可用于当水印。
    transcodeOptions.videoOptions.layout.ImageView 元素.imageUrl String 图片的 HTTP(S) URL。
    transcodeOptions.videoOptions.layout.ImageView 元素.region JSON Object 图片在画布上的显示区域。
    transcodeOptions.videoOptions.
    layout.ImageView 元素.region.xPos    		 Number 图片在画布上的 x 坐标 (pixel)。以画布左上角为原点，x 坐标为图片左上角相对于原点的横向位移。
    transcodeOptions.videoOptions.
    layout.ImageView 元素.region.yPos    		 Number 图片在画布上的 y 坐标 (pixel)。以画布左上角为原点，y 坐标为图片左上角相对于原点的纵向位移。
    transcodeOptions.videoOptions.
    layout.ImageView 元素.region.zIndex    		 Number 图片的图层编号。取值范围为 [0,100]。0 代表最下层的图层。100 代表最上层的图层。
    transcodeOptions.videoOptions.
    layout.ImageView 元素.region.width    		 Number 图片的宽度 (pixel)。
    transcodeOptions.videoOptions.
    layout.ImageView 元素.region.height    		 Number 图片的高度 (pixel)。
    transcodeOptions.videoOptions.
    layout.ImageView 元素.fillMode    		 String 图片的显示方式。
  • fill：在保持长宽比的前提下，缩放图片，使图片充满容器。
  • fit：在保持长宽比的前提下，缩放图片，使得图片在容器内完整显示出来。
    • transcodeOptions.videoOptions.bitrate Number 输出视频的编码码率 (Kbps)。
    transcodeOptions.videoOptions.frameRate Number 输出视频的编码帧率 (fps)。
    transcodeOptions.videoOptions.codecProfile String 输出视频的编码规格。
    transcodeOptions.videoOptions.seiOptions String 输出视频中携带的用户 SEI 信息。用于向 CDN 发送用户自定义的 SEI 信息。
    rtmpUrl String CDN 推流地址。
    idleTimeout Number Converter 处于空闲状态的最大时长（秒）。空闲指 Converter 处理的音视频流所对应的所有用户均已离开频道。取值范围为 [5,600]。默认值为 300。取值超出范围会报错。
    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."
}

    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.

    注意事项

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

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

    最佳实践

    为保障 CDN 直播推流场景下用户体验，避免频繁出现推流异常，你可以参考以下内容优化 CDN 推流的业务逻辑。

    错误码排查

    请在发起推流请求后，根据响应报文的状态码进行处理。

    Create：创建一个 Converter

    状态码           原因 建议措施
    200 创建成功 无
    409 已存在相同名称的 Converter 删除已有 Converter 并重新创建
    429 并发请求过多 采用退避策略重试，即依次等待 5-6 秒、10-11 秒、15-16 秒重试
    4xx（除 409、429） 请求参数错误 参考 HTTP 响应 Body 中的 reason 字段进行排查
    5xx 服务内部出错 使用退避策略重试

    Update：更新指定的 Converter

    状态码           原因 建议措施
    200 操作成功 无
    429 并发请求过多 采用退避策略重试，即依次等待 5-6 秒、10-11 秒、15-16 秒重试
    404 推流并未成功启动、或启动后中途退出、或自动迁移中 采用退避策略重试，即依次等待 5-6 秒、10-11 秒、15-16秒重试
    4xx（除 409、429） 请求参数错误 参考 HTTP 响应 Body 中的 reason 字段进行排查
    5xx 服务内部出错 采用退避策略重试，即依次等待 5-6 秒、10-11 秒、15-16秒重试

    更新 rtmpUrl 字段会使服务器与已有 rtmpUrl 断开，再重新连接新的 rtmpUrl，导致一定延时。请在必要时更新 rtmpUrl。

    Delete: 销毁指定的 Converter

    状态码           原因 建议措施
    200 操作成功 无
    404 指定 ID 不存在 无，已销毁指定 Converter
    429 并发请求过多 采用退避策略重试，即依次等待 5-6 秒、10-11 秒、15-16秒重试
    4xx（除 409、429） 请求参数错误 参考 HTTP 响应 Body 中的 reason 字段进行排查
    5xx 服务内部出错 采用退避策略重试，即依次等待 5-6 秒、10-11 秒、15-16秒重试

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

    如果你对状态可靠性要求较高，建议使用 GET 方法周期性查询推流状态，例如每隔 10 秒调用一次 GET。

    状态码           原因 建议措施
    200 操作成功 无
    404
  • 推流并未成功
  • 开始推流开始后中途退出
  • 正在恢复推流
    		•  采用退避策略重试，即依次等待 5-6 秒、10-11 秒、15-16秒重试
    4xx 请求参数错误 参考 HTTP 响应 Body 中的 reason 字段进行排查
    5xx 服务内部出错 采用退避策略重试，即依次等待 5-6 秒、10-11 秒、15-16秒重试

    使用退避策略重试后，如果连续 3 次响应 Body 中的 state 字段为 failed，说明推流失败，请按照以下步骤再次排查：

    • 确认 CDN 推流地址是否正确。
    • 如果 CDN 推流地址正确，Agora 推荐你 Delete 该 Converter，再重新创建。

    避免服务频繁退出

    如果直播场景中主播频繁上下线，过短的 idleTimeout 会导致推流服务频繁退出。对于需要在频道中持续推流的场景，需要在 Create 方法中设置较长的 idleTimeout。