Use RESTful API

This article contains detailed help for the Media Push RESTful APIs.

The RESTful APIs require basic HTTP authentication. You need to set the Authorization parameter in every HTTP request header. For how to get the value for Authorization, see RESTful API authentication.

You can implement different types of Media Push depending on the live streaming scenario requires transcoded or non-transcoded streaming. Transcoding is essentially an encoding and decoding function used to mix multiple audio and video streams into one audio and video stream, which can guarantee the synchronization of multiple hosts' live streams seen by the audience. Therefore, generally speaking, in the case of multiple-hosts live streaming, you need to enable transcoding when pushing streams to CDN; in the case of single-host live streaming, only one media stream is pushed to the CDN, so you do not need to enable transcoding. Processing the media streams and pushing it to the CDN creates a Media Push task (shown as "Converter" in the rest of the article) in the Agora channel. You can control a Converter through the following methods:

• Create: Create a Converter for your project, and set up the relevant configuration of transcoded or non-transcoded streaming. The media stream in the channel is processed by the Converter according to this configuration and then pushed to the CDN.
• Delete: Destroy the specified Converter. The user's media stream in this channel will no longer be processed by the Converter or pushed to the CDN after you destroy the Converter.
• Update: Update the specified Converter configuration.
• Get: Get the streaming status of the specified Converter.

_1

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

• appId: (Required) String. The App ID provided by Agora. You can get an App ID after creating a project in the Agora console. An App ID is the unique identification of a project.
• region: (Required) String. The region that the Converter was created in. Agora supports the creation of Converters in different regions. Currently, four regions are supported:
  • cn: China Mainland
  • ap: Asia, excluding Mainland China
  • na: North America
  • eu: Europe

Please ensure that the region you set is the same region as where your CDN originates is located.

Please make sure the value of region is lowercase.

regionHintIp: (Optional) String. The IP address of the CDN source station. It must be a valid IPv4 address. This parameter can help ensure the stability of the RTMP stream.

_1

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

• Content-Type: application/json

• Authorization: The value of this field must refer to the Authentication instructions.

• X-Request-ID: The UUID (Universal Unique Identifier) that identifies this request. Agora server generates a UUID to pass in and returns X-Request-ID field in the response header.

  Agora recommends that you assign a value to X-Request-ID. Agora server returns an X-Custom-Request-ID field in the response header for trouble shooting.

Request body​

You can implement different types of Media Push depending on the live streaming scenario requires transcoded or non-transcoded streaming. Generally speaking, in the case of multiple-hosts live streaming, you need to enable transcoding when using Media Push RESTful APIs; in the case of single-host live streaming, only one media stream is pushed to the CDN, so you do not need to enable transcoding. For details, see Media Push Features.

Media Push with transcoding

The request Body is the converter field of JSON Object type. The field structure is shown in the following figure:

Details for these fields are shown in the following table:

Field	Type	Descriptions
name	(Optional) String	The name of the Converter. The maximum length is 64 characters. The supported character set range is: All lowercase English letters (a-z) All uppercase English letters (A-Z) Numbers 0-9 "-", "_" The field is empty when no value is passed. Multiple converters with an empty name field can be created under a project. Two converters cannot have the same name, however; you will receive a response status code of 409 (Conflict) if you try to create a converter with the same name as one that already exists under that project. To avoid repeatedly creating multiple Converters and repetitively pushing streams, please use the name field to manage the Converters under the specified project. Agora recommends that you combine "channel name (rtcChannel)" and "Converter feature" to assign a value to the name. For example, show68_horizontal and show68_vertical would represent converters for the user screen created in channel show68 with horizontal and vertical layouts, respectively.
transcodeOptions	(Required) JSON Object	The Converter’s transcoding configuration. When the audioOptions and videoOptions fields in converter.transcodeOptions are not defined, the converter will output a video stream only (without audio). When there is no rtcStreamUids field in the converter.transcodeOptions.audioOptions field, Agora will mix the audio streams of all users in the channel and output the mixed audio stream through the Converter. When there is an rtcStreamUids field in the converter.transcodeOptions.audioOptions field, Agora will mix the audio stream of the specified user and output the mixed audio stream through the Converter.
transcodeOptions.rtcChannel	(Required) String	The Agora channel name. This is the channel to which the stream processed by the Converter belongs. The maximum length of the string is 64 characters, and the following character sets (89 characters in total) are supported: All lowercase English letters (a-z) All uppercase English letters (A-Z) Numbers 0-9 The space character "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " , ", "|", "~", ","
transcodeOptions.audioOptions	(Optional) JSON Object	The audio transcoding configuration of the Converter. See audioOptions for details. There is no need to set audioOptions and related fields in a video stream only (without audio) scenario. In an audio & video scenario, audioOptions is a required field. If there is no field setting requirement, you can set audioOptions to empty, for example: "audioOptions":
transcodeOptions.videoOptions	(Optional) JSON Object	The video transcoding configuration of the Converter. There is no need to set videoOptions and related fields in an audio stream only (without video) scenario. In an audio & video scenario, videoOptions is a required field and cannot be empty.
transcodeOptions.videoOptions.canvas	(Required) JSON Object	The video canvas. See canvas for details.
transcodeOptions.videoOptions.layoutType	(Optional) Number	The screen layout type of the output video: 0 or empty: (Default) Custom layout, which is set through thetranscodeOptions.videoOptions.layout parameter. 1: Vertical layout. Specify one user to display in the large window on the left side of the screen, while the other users are vertically arranged in the small windows on the right side of the screen. For details, see Set Vertical Layout.
transcodeOptions.videoOptions.layout	(Optional) JSON Array	The content description of the video screen on the canvas. Two elements are supported: RtcStreamView and ImageView. If layoutType is 0 or empty, this field is required.
transcodeOptions.videoOptions.layout.RtcStreamView element	None	The video screen of each user on the canvas. See RtcStreamView for details.
transcodeOptions.videoOptions.layout.ImageView element	None	The video image on the canvas, which can be used as a watermark. See ImageView for details.
transcodeOptions.videoOptions.vertical	(Optional) JSON Object	Vertical layout. This parameter must be set when layoutType is 1. See vertical for details.
transcodeOptions.videoOptions.defaultPlaceholderImageUrl	(Required) String	The default user screen background image URL address. Supports images in JPG, PNG and GIF formats. This controls what happens when a user in a channel stops publishing their video stream: If this field is set, the user's window switches to this background image. If this field is not set, the user's window initially displays the last frame of the user's video. Once the layout refreshes, the window displays the background color of the canvas.
transcodeOptions.videoOptions.bitrate	(Required) Number	The encoding bitrate (Kbps) of the video. The value range is [1,10000].
transcodeOptions.videoOptions.gop	(Optional) Number	The GOP of the video. The defalt value is the value of frameRate * 2。
transcodeOptions.videoOptions.frameRate	(Optional) Number	The encoding frame rate (fps) of the video. The value range is [1,30]. The default value is 15.
transcodeOptions.videoOptions.codec	(Optional) String	The video codec type of the output video stream. The following values are supported: (Default) H.264 H.265
transcodeOptions.videoOptions.codecProfile	(Optional) String	The encoding specification of the video. The following values are supported: high (Default): High video codec profile, generally used for high-resolution broadcasts or television. baseline: Baseline video codec profile, generally used for video calls on mobile phones. main: Main video codec profile, generally used for mainstream electronics, such as MP4 players, portable video players, PSPs, and iPads. If codec is set to H.256, codecProfile is automatically set to main.
transcodeOptions.videoOptions.seiOptions	JSON Object	Sets the user SEI information carried in the output video stream. The default is empty. If it is not set, it means that no SEI information is output. See seiOptions for details.
rtmpUrl	(Required) String	The address of Media Push. It must be a valid RTMP address with a length of 1,024 characters or less.
idleTimeOut	(Optional) Number	The maximum time (seconds) that the Converter is idle. Idle means that all users corresponding to the media stream processed by the Converter have left the channel. After the idle state exceeds the set idleTimeOut, the Converter will be destroyed automatically.
jitterBufferSizeMs	(Optional) Int	Network delay (ms) from the receiver to the jitter buffer. The default value is 1000. The value range is [0, 1000]. The Media Push service rounds up to the nearest 100 multiples with the value you set. If the value is set to 0, jitter buffer delay does not take effect. Agora recommends that you do not set the jitterBufferSizeMs to 0 because poor network may cause low audio quality.

Media Push without transcoding

The request body is the converter field of JSON Object type. The field structure is shown in the following figure:

Details for these fields are shown in the following table:

Field	Category	Description
name	String	The name of the Converter.
rawOptions	(Required)JSON Object	Media Push configuration for the Converter.
rawOptions.rtcChannel	String	The Agora channel name. The channel to which the stream processed by the Converter belongs.
rawOptions.rtcStreamUid	Number	The UID of the user to which the media stream belongs.
rtmpUrl	(Required)String	The CDN streaming address.
idleTimeOut	Number	The maximum time (s) that the Converter is idle. Idle means that all users of the corresponding media streams processed by the Converter have left the channel. When the Converter is in the idle state for longer than idleTimeout, the Converter is automatically destroyed and the streaming stops.
jitterBufferSizeMs	(Optional) Int	Network delay (ms) from the receiver to the jitter buffer. The default value is 1000. The value range is [0, 1000]. The Media Push service rounds up to the nearest 100 multiples with the value you set. If the value is set to 0, jitter buffer delay does not take effect. Agora recommends that you do not set the jitterBufferSizeMs to 0 because poor network may cause low audio quality.

All possible response status codes. See Status codes for details.

• X-Request-ID: The UUID (Universal Unique Identifier) that identifies this request. This value is the same as the X-Request-ID in the header of this request. If there is an error in the request, please print out the value in the log to troubleshoot the problem.

  If the response status code of this request is not 2XX, this field may be missing from the response header.

• X-Resource-ID: The UUID (Universal Unique Identifier) that identifies the ID of the Converter updated in this request.

If the status code is 2XX, the request is successful. The field structure is shown in the following figure:

Details for these fields are shown in the following table:

Field	Type	Descriptions
id	String	The ID of the Converter. This is a UUID (Universal Unique Identifier) generated by the Agora server to identify a created Converter.
createTs	Number	The Unix timestamp(seconds) when the Converter was created.
updateTs	Number	The Unix timestamp(seconds) when the Converter configuration was last updated.
state	String	The running status of the Converter: idle: The Media Push has not started or has ended. connecting: Connecting to the Agora streaming server and the CDN server. running: The Agora streaming server is pushing the streams. failed: The Media Push fails.
fields	String	The field mask of the converter JSON Object. See Google protobuf FieldMask Document for details. This is used to describe the set of fields contained in the returned converter. In this example, fields specifies that the Agora server returns a subset of the id, createTs, updateTs and state fields in the converter field.

If the status code is not 2XX, the request fails. The body contains a String type message field that describes the specific reason for the failure.

_3

{

_3

"message": "Invalid authentication credentials."

_3

}

Custom layout for Media Push with transcoding

This example shows that the video of the two specified users in the show68 channel are mixed with a custom layout and pushed to the CDN. The audio of all users in the channel is also mixed.

_50

{

_50

"converter": {

_50

"name": "show68_vertical",

_50

"transcodeOptions": {

_50

"rtcChannel": "show68",

_50

"audioOptions": {

_50

"codecProfile": "LC-AAC",

_50

"sampleRate": 48000,

_50

"bitrate": 48,

_50

"audioChannels": 1

_50

},

_50

"videoOptions": {

_50

"canvas": {

_50

"width": 360,

_50

"height": 640

_50

},

_50

"layout": [

_50

{

_50

"rtcStreamUid": 201,

_50

"region": {

_50

"xPos": 0,

_50

"yPos": 0,

_50

"zIndex": 1,

_50

"width": 360,

_50

"height": 320

_50

},

_50

"fillMode": "fill",

_50

"placeholderImageUrl": "http://example.agora.io/user_placeholder.jpg"

_50

},

_50

{

_50

"rtcStreamUid": 202,

_50

"region": {

_50

"xPos": 0,

_50

"yPos": 320,

_50

"zIndex": 1,

_50

"width": 360,

_50

"height": 320

_50

}

_50

}

_50

],

_50

"codecProfile": "High",

_50

"frameRate": 15,

_50

"gop": 30,

_50

"bitrate": 400,

_50

"seiOptions": {}

_50

}

_50

},

_50

"rtmpUrl": "rtmp://example/live/show68"

_50

}

_50

}

The sample code for setting SEI information (seiOptions) is as follows:

_20

{

_20

"converter": {

_20

"transcodeOptions": {

_20

"videoOptions": {

_20

"seiOptions": {

_20

"source": {

_20

"metadata": true,

_20

"datastream": true,

_20

"customized": {

_20

"payload": "example"

_20

}

_20

},

_20

"sink": {

_20

"type": 100

_20

}

_20

}

_20

}

_20

}

_20

}

_20

}

Vertical layout for Media Push with transcoding This example shows that the video of the two specified users in the show68 channel are mixed with a vertical layout and pushed to the CDN. The audio of two specified users in the channel are mixed.

_75

{

_75

"converter": {

_75

"name": "show68_vertical",

_75

"transcodeOptions": {

_75

"rtcChannel": "show68",

_75

"audioOptions": {

_75

"codecProfile": "HE-AAC",

_75

"sampleRate": 48000,

_75

"bitrate": 128,

_75

"audioChannels": 1,

_75

"rtcStreamUids": [

_75

201,

_75

202

_75

]

_75

},

_75

"videoOptions": {

_75

"canvas": {

_75

"width": 360,

_75

"height": 640,

_75

"color": 0

_75

},

_75

"layout": [

_75

{

_75

"rtcStreamUid": 201,

_75

"region": {

_75

"xPos": 0,

_75

"yPos": 0,

_75

"zIndex": 1,

_75

"width": 360,

_75

"height": 640

_75

},

_75

"fillMode": "fill",

_75

"placeholderImageUrl": "http://example/host_placeholder.jpg"

_75

},

_75

{

_75

"rtcStreamUid": 202,

_75

"region": {

_75

"xPos": 0,

_75

"yPos": 320,

_75

"zIndex": 1,

_75

"width": 360,

_75

"height": 320

_75

}

_75

}

_75

],

_75

"codec": "H.264",

_75

"codecProfile": "high",

_75

"frameRate": 15,

_75

"gop": 30,

_75

"bitrate": 400,

_75

"layoutType": 1,

_75

"vertical": {

_75

"maxResolutionUid": 201,

_75

"fillMode": "fill",

_75

"refreshIntervalSec": 4

_75

},

_75

"defaultPlaceholderImageUrl": "http://example/host_placeholder.jpg",

_75

"seiOptions": {

_75

"source": {

_75

"metadata": true,

_75

"datastream": true,

_75

"customized": {

_75

"payload": "example"

_75

}

_75

},

_75

"sink": {

_75

"type": 100

_75

}

_75

}

_75

}

_75

},

_75

"rtmpUrl": "rtmp://example/live/show68",

_75

"idleTimeout": 300

_75

}

_75

}

Media Push without transcoding

This example shows that the media stream of the specified user in the show68 channel is pushed to the CDN.

_10

{

_10

"converter": {

_10

"name": "show68_vertical",

_10

"rawOptions": {

_10

"rtcChannel": "show68",

_10

"rtcStreamUid": 201

_10

},

_10

"rtmpUrl": "rtmp://example/live/global"

_10

}

_10

}

_9

{

_9

"converter": {

_9

"id": "4c014467d647bb87b60b719f6fa57686",

_9

"createTs": 1591786766,

_9

"updateTs": 1591786766,

_9

"state": "connecting"

_9

},

_9

"fields": "id,createTs,updateTs,state"

_9

}

_1

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

• region: (Required) String. The region where the Converter is created in, which must be the same as the region set when creating Converter.
• appId: (Required) String type parameter. The App ID provided by Agora . You can get an App ID after creating a project in the Agora console. An App ID is the unique identification of a project.
• converterId: (Required) String type parameter. The ID of the Converter.

• Authorization: The value of this field must refer to the Authentication instructions.

• X-Request-ID: The UUID (Universal Unique Identifier) that identifies this request. Agora server generates a UUID to pass in and returns X-Request-ID field in the response header.

  Agora recommends that you assign a value to X-Request-ID. Agora server returns an X-Custom-Request-ID field in the response header for trouble shooting.

All possible response status codes. See Status codes for details.

• X-Request-ID: The UUID (Universal Unique Identifier) that identifies this request. This value is the same as the X-Request-ID in the header of this request. If there is an error in the request, please print out the value in the log to troubleshoot the problem.

  If the response status code of this request is not 2XX, this field may be missing from the response header.

• X-Resource-ID: The UUID (Universal Unique Identifier) that identifies the ID of the Converter created in this request.

• If the status code is 2XX, the request is successful. The body is empty.
• If the status code is not 2XX, the request fails. The body contains a String type message field that describes the specific reason for the failure.

_1

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

• region: (Required) String. The region where the Converter is created in, which must be the same as the region set when creating Converter.
• appId: (Required) String type parameter. The App ID provided by Agora. You can get an App ID after creating a project in the Agora console. An App ID is the unique identification of a project.
• converterId: (Required) String type parameter. The ID of the Converter.

sequence: (Required) Number type parameter. The serial number of the Update request. The value must be greater than or equal to 0. Please make sure that the serial number of the next Update request is greater than the serial number of the previous Update request. The serial number can ensure that the Agora server updates the Converter according to the latest configuration you specify.

Agora recommends that you fill in sequence sequentially, using 0 when calling Update for the first time, 1 for the second time, 2 for the third time, and so on. The Agora server will update the Converter according to the latest Update request (the largest serial number).

_1

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

• Content-Type: application/json

• Authorization: The value of this field must refer to the Authentication instructions.

• X-Request-ID: The UUID (Universal Unique Identifier) that identifies this request. Agora server generates a UUID to pass in and returns X-Request-ID field in the response header.

  Agora recommends that you assign a value to X-Request-ID. Agora server returns an X-Custom-Request-ID field in the response header for trouble shooting.

For details about the fields, see the Create request body.

Update method does not support updating the following configurations of a 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

After calling the Create method to create a Converter that outputs video stream only or audio stream only, you cannot update it to a Converter that outputs audio stream only or video stream only through the Update method.

When using Media Push with vertical layout (layoutType is 1), you can only update the rtmpUrl field.

All possible response status codes. See Status codes for details.

• X-Request-ID:The UUID (Universal Unique Identifier) that identifies this request. This value is the same as the X-Request-ID in the header of this request. If there is an error in the request, please print out the value in the log to troubleshoot the problem.

  If the response status code of this request is not 2XX, this field may be missing from the response header.

• X-Resource-ID: The UUID (Universal Unique Identifier) that identifies the ID of the Converter updated in this request.

If the status code is 2XX, the request is successful. The field structure is shown in the following figure:

Details of these fields are shown in the following table:

Field	Type	Descriptions
id	String	The ID of the Converter. This is a UUID (Universal Unique Identifier) generated by the Agora server to identify a created Converter.
createTs	Number	The Unix timestamp(seconds) when the Converter was created.
updateTs	Number	The Unix timestamp(seconds) when the Converter configuration was last updated.
state	String	The running status of the Converter: idle: The Media Push has not started or has ended. connecting: Connecting to the Agora streaming server and the CDN server. running: The Agora streaming server is pushing the streams. failed: The Media Push Fails.
fields	String	The field mask of the converter JSON Object. See Google protobuf FieldMask Document for details. This is used to describe the set of fields contained in the returned converter. In this example, fields specifies that the Agora server returns a subset of the id, createTs, updateTs, and state fields in the converter field.

If the status code is not 2XX, the request fails. The body contains a String type message field that describes the specific reason for the failure.

You can update multiple fields at the same time, such as updating transcodeOptions.videoOptions.canvas and converter.transcodeOptions.videoOptions.layout. Refer to the following sample code:

_28

{

_28

"converter": {

_28

"transcodeOptions": {

_28

"videoOptions": {

_28

"canvas": {

_28

"width": 360,

_28

"height": 640,

_28

"color": 0

_28

},

_28

"layout": [

_28

{

_28

"rtcStreamUid": 201,

_28

"region": {

_28

"xPos": 0,

_28

"yPos": 0,

_28

"zIndex": 1,

_28

"width": 360,

_28

"height": 320

_28

},

_28

"fillMode": "fill",

_28

"placeholderImageUrl": "http://example/host_placeholder.jpg"

_28

}

_28

]

_28

}

_28

}

_28

},

_28

"fields": "transcodeOptions.videoOptions.canvas,transcodeOptions.videoOptions.layout"

_28

}

_9

{

_9

"converter": {

_9

"id": "4c014467d647bb87b60b719f6fa57686",

_9

"createTs": 1591786766,

_9

"updateTs": 1591788746,

_9

"state": "running"

_9

},

_9

"fields": "id,createTs,updateTs,state"

_9

}

_1

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

• region: (Required) String. The region where the Converter is created in, which must be the same as the region set when creating Converter.
• appId: (Required) String type parameter. The App ID provided by Agora . You can get an App ID after creating a project in the Agora console. An App ID is the unique identification of a project.
• converterId: (Required) String type parameter. The ID of the Converter.

• Content-Type: application/json

• Authorization: The value of this field must refer to the Authentication instructions.

• X-Request-ID: The UUID (Universal Unique Identifier) that identifies this request. Agora server generates a UUID to pass in and returns X-Request-ID field in the response header.

  Agora recommends that you assign a value to X-Request-ID. Agora server returns an X-Custom-Request-ID field in the response header for trouble shooting.

All possible response status codes. See Status codes for details.

• X-Request-ID: The UUID (Universal Unique Identifier) that identifies this request. This value is the same as the X-Request-ID in the header of this request. If there is an error in the request, please print out the value in the log to troubleshoot the problem.

  If the response status code of this request is not 2XX, this field may be missing from the response header.

• X-Resource-ID: The UUID (Universal Unique Identifier) that identifies the ID of the Converter created in this request.

If the status code is 2XX, the request is successful. The field structure is shown in the following figure:

Details of these fields are shown in the following table:

Field	Type	Descriptions
name	String	The name of the Converter.
transcodeOptions	JSON Object	The transcoding configuration of the Converter.
transcodeOptions.rtcChannel	String	The Agora channel name.
transcodeOptions.audioOptions	JSON Object	The audio transcoding configuration of the Converter. See audioOptions for details.
transcodeOptions.videoOptions	JSON Object	The video transcoding configuration of the Converter.
transcodeOptions.videoOptions.canvas	JSON Object	The video canvas. See canvas for details.
transcodeOptions.videoOptions.layout	JSON Array	The content description of the video screen on the canvas. Two elements are supported: RtcStreamView and ImageView.
transcodeOptions.videoOptions.layout.RtcStreamView element	NA	The video screen of each user on the canvas. See RtcStreamView for details.
transcodeOptions.videoOptions.layout.ImageView element	NA	The video image on the canvas, which can be used as a watermark. See ImageView for details.
transcodeOptions.videoOptions.bitrate	Number	The encoding bitrate (Kbps) of the video.
transcodeOptions.videoOptions.frameRate	Number	The encoding frame rate (fps) of the video.
transcodeOptions.videoOptions.codec	String	The video codec type of the output video stream.
transcodeOptions.videoOptions.codecProfile	String	The encoding specification of the video.
transcodeOptions.videoOptions.seiOptions	JSON Object	The user SEI information carried in the output video stream. See seiOptions for details.
rtmpUrl	String	The address of Media Push.
idleTimeout	Number	The maximum time (seconds) that the Converter is idle. Idle means that all users corresponding to the media stream processed by the Converter have left the channel.
createTs	Number	The Unix timestamp(seconds) when the Converter was created.
state	String	The running status of the Converter: idle: Pushing the stream has not started or has ended. connecting: Connecting to the Agora streaming server and the CDN server. running: Pushing the stream. failed: Failed to push the stream.

If the status code is not 2XX, the request fails. The body contains a String type message field that describes the specific reason for the failed.

_3

{

_3

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

_3

}

Media Push without transcoding

If the status code is 2XX, the request is successful. The field structure is shown in the following figure:

Details of these fields are shown in the following table:

Field name	Category	Description
name	String	The name of the Converter.
rawOptions	JSON Object	Media Push configuration for the Converter.
rawOptions.rtcChannel	String	The Agora channel name. The channel to which the stream processed by the Converter belongs.
rawOptions.rtcStreamUid	Number	The UID of the user to which the media stream belongs.
rtmpUrl	String	The CDN streaming address.
idleTimeOut	Number	The maximum time (s) that the Converter is idle. Idle means that all users of the corresponding media streams processed by the Converter have left the channel. When the Converter is in the idle state for longer than idleTimeout, the Converter is automatically destroyed and the streaming stops.

Custom layout for Media Push with transcoding

If the status code is 2XX, the request is successful.

_68

{

_68

"name": "show68_vertical",

_68

"transcodeOptions": {

_68

"rtcChannel": "show68",

_68

"audioOptions": {

_68

"codecProfile": "HE-AAC",

_68

"sampleRate": 48000,

_68

"bitrate": 128,

_68

"audioChannels": 1,

_68

"rtcStreamUids": [

_68

201

_68

]

_68

},

_68

"videoOptions": {

_68

"canvas": {

_68

"width": 360,

_68

"height": 640,

_68

"color": 0

_68

},

_68

"layout": [

_68

{

_68

"rtcStreamUid": 201,

_68

"region": {

_68

"xPos": 0,

_68

"yPos": 0,

_68

"zIndex": 1,

_68

"width": 360,

_68

"height": 320

_68

},

_68

"fillMode": "fill",

_68

"placeholderImageUrl": "http://example.agora.io/host_placeholder.jpg"

_68

},

_68

{

_68

"rtcStreamUid": 202,

_68

"region": {

_68

"xPos": 0,

_68

"yPos": 320,

_68

"zIndex": 1,

_68

"width": 360,

_68

"height": 320

_68

}

_68

},

_68

{

_68

"imageUrl": "http://example.agora.io/watchmark.jpg",

_68

"region": {

_68

"xPos": 0,

_68

"yPos": 0,

_68

"zIndex": 2,

_68

"width": 36,

_68

"height": 64

_68

},

_68

"fillMode": "fit"

_68

}

_68

],

_68

"codec": "H.264",

_68

"codecProfile": "High",

_68

"frameRate": 15,

_68

"gop": 30,

_68

"bitrate": 400,

_68

"seiOptions": {}

_68

}

_68

},

_68

"rtmpUrl": "rtmp://example.agora.io/live/show68",

_68

"idleTimeout": 300,

_68

"createTs": 1616946970,

_68

"updateTs": 1783656785,

_68

"state": "running"

_68

}

Vertical layout for Media Push with transcoding

If the status code is 2XX, the request is successful.

_62

{

_62

"name": "show68_vertical",

_62

"transcodeOptions": {

_62

"rtcChannel": "show68",

_62

"audioOptions": {

_62

"codecProfile": "HE-AAC",

_62

"sampleRate": 48000,

_62

"bitrate": 128,

_62

"audioChannels": 1,

_62

"rtcStreamUids": [

_62

201

_62

]

_62

},

_62

"videoOptions": {

_62

"canvas": {

_62

"width": 360,

_62

"height": 640,

_62

"color": 0

_62

},

_62

"layout": [

_62

{

_62

"rtcStreamUid": 201,

_62

"region": {

_62

"xPos": 0,

_62

"yPos": 0,

_62

"zIndex": 1,

_62

"width": 360,

_62

"height": 640

_62

},

_62

"fillMode": "fill",

_62

"placeholderImageUrl": "http://example.agora.io/host_placeholder.jpg"

_62

}

_62

],

_62

"codec": "H.264",

_62

"codecProfile": "high",

_62

"frameRate": 15,

_62

"gop": 30,

_62

"bitrate": 400,

_62

"layoutType": 1,

_62

"vertical": {

_62

"maxResolutionUid": 201,

_62

"fillMode": "fill",

_62

"refreshIntervalSec": 4

_62

},

_62

"defaultPlaceholderImageUrl": "http://example.agora.io/host_placeholder.jpg",

_62

"seiOptions": {

_62

"source": {

_62

"metadata": true,

_62

"datastream": true,

_62

"customized": {

_62

"payload": "example"

_62

}

_62

},

_62

"sink": {

_62

"type": 100

_62

}

_62

}

_62

}

_62

},

_62

"rtmpUrl": "rtmp://example.agora.io/live/show68",

_62

"idleTimeout": 300

_62

}

Media Push without transcoding

_11

{

_11

"converter": {

_11

"name": "wX8210Ce1VWVyGVHyaHA0W",

_11

"rawOptions": {

_11

"rtcChannel": "example",

_11

"rtcStreamUid": XXXX

_11

},

_11

"rtmpUrl": "rtmp://vid-218.push.chinanetcenter.broadcastapp.agora.io/live/global",

_11

"idleTimeout": 120

_11

}

_11

}

• Query all Converters under a project: GET https://api.agora.io/v1/projects/{appId}/rtmp-converters

• Query the Converter of a specified channel under a project: GET https://api.agora.io/v1/projects/{appId}/channels/{cname}/rtmp-converters

• appId: (Required) String. The App ID provided by Agora. You can get an App ID after creating a project in the Agora console. An App ID is the unique identification of a project.

• cname: (Required) String. The Agora channel name. This is the channel to which the stream processed by the Converter belongs. The maximum length of the string is 64 characters, and the following character sets (89 characters in total) are supported:

• All lowercase English letters (a-z)

• All uppercase English letters (A-Z)

• Numbers 0-9The space character

• "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " , ", "|", "~", ","

cursor: (Optional) String. Cursor for paging query Converters. The value must be greater than or equal to 0.

• You do not need to set the cursor when you initiate a List request for the first time. After the request is successful, the list of Converters on the first page return.
• Each request returns information about a maximum of 500 Converters.. If the number of Converters under the project exceeds 500, get the cursor from the response body, and pass the cursor in the URL of the next request. Until the value of the cursor field in the response body is 0, it means that all Converters under the project or the specified channel have been queried.

The HTTP URL using Query Parameters is as follows:

• Query all Converters under a project: GET https://api.agora.io/v1/projects/{appId}/rtmp-converters?cursor={cursor}

• Query the Converter of a specified channel under a project: GET https://api.agora.io/v1/projects/{appId}/channels/{cname}/rtmp-converters?cursor={cursor}

• Content-Type: application/json

• Authorization: The value of this field must refer to the Authentication instructions.

• X-Request-ID: The UUID (Universal Unique Identifier) that identifies this request. Agora server generates a UUID to pass in and returns X-Request-ID field in the response header.

  Agora recommends that you assign a value to X-Request-ID. Agora server returns an X-Custom-Request-ID field in the response header for troubleshooting.

All possible response status codes. See Status codes for details.

X-Request-ID: The UUID (Universal Unique Identifier) that identifies this request. This value is the same as the X-Request-ID in the header of this request. If there is an error in the request, print out the value in the log to troubleshoot the problem.

If the response status code of this request is not 2XX, this field may be missing from the response header.

If the status code is 2XX, the request is successful. The field structure is shown in the following figure:

Details for these fields are shown in the following table:

Field	Type	Descriptions
success	Bool	The request was successful.
data	JSON Object	Returns data details.
data.total_count	String	The number of all Converters under the queried project or channel.
data.cursor	JSON	Cursor for paging query Converter information list. If the cursor is 0, it means that all Converters under the project or the specified channel have been queried; otherwise, the query needs to be continued.
data.members.rtcChannel	String	The Agora channel name. This is the channel to which the stream processed by the Converter belongs.
data.members.converterName	String	The name of the Converter.
data.members.updateTs	Number	The Unix timestamp(seconds) when the Converter configuration was last updated.
data.members.appId	String	The App ID provided by Agora . You can get an App ID after creating a project in the Agora console. An App ID is the unique identification of a project.
data.members.rtmpUrl	String	The CDN streaming address.
data.members.converterId	String	The ID of the Converter. The unique identifier for the Converter.
data.members.create	Number	The Unix timestamp(seconds) when the Converter was created.
data.members.idleTimeout	Number	The maximum time (seconds) that the Converter is idle. Idle means that all users corresponding to the media stream processed by the Converter have left the channel.
data.members.state	String	The running status of the Converter: idle: Pushing the stream has not started or has ended. connecting: Connecting to the Agora streaming server and the CDN server. running: Pushing the stream. failed: Failed to push the stream.

_22

{

_22

"success": true,

_22

"data": {

_22

"total_count": 1,

_22

"cursor": 0,

_22

"members": [

_22

{

_22

"rtcChannel": "testchannel",

_22

"status": "200",

_22

"converterName": "wX8210XXXXWVyGVHyaHA0W",

_22

"updateTs": "1641267823",

_22

"appId": "aab8b8f5a8cd4469a63042fcfafe7063",

_22

"rtmpUrl": "rtmp://example/live/areu",

_22

"ip": "183.131.160.244",

_22

"converterId": "889B6D4BEC4XXXXE68CCDA978BF21350",

_22

"create": "1641267818",

_22

"idleTimeout": "120",

_22

"state": "running"

_22

}

_22

]

_22

}

_22

}

The Agora server limits the call rate for the Media Push API by method. When a call rate exceeds its limit, the status code 429 (Too Many Requests) is returned. If you need a higher call rate, please contact technical support.

API	Rate limits
Create	In a project, the rate limit for the rate of creating a Converter is 50 times per second.
Delete	In a project, the rate limit for the converter destruction is 50 times per second.
Update	In a project, the rate limit for the rate of updating a specified Converter is 2 times per second.
Get	In a project, the rate limit for the rate of getting the status of a specified Converter is 50 times per second.

Status codes​

• If the status code is 2XX, the request is successful.
• If the status code is not 2XX, the request fails. Please troubleshoot the problem based on the content of the message field in the corresponding response message Body.

Status codes	Possible message field content
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	The project lacks permission to use this function. Contact Agora technical support.
404 Not Found	Resource cannot be found/has been destroyed.
409 Conflict	Resource with the same name already exists. 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 Agora for assistance with 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 Agora for assistance with 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.

This section summarizes the most important considerations for using the Media Push RESTful API.

Note	Influence level
Please make sure that the Agora channel scene is live.	★★★☆☆
If you need only one Converter in a channel, you must use the name parameter. See the name parameter explanation for details.	★★★☆☆
Please ensure that the region you set is the same region as where your CDN originates is located. For details, see the description of region.	★★★★★
If a Converter is automatically destroyed due to service failures (or other reasons), Agora recommends that you create a new Converter.	★★★★★
After creating a Converter, if the CDN side pulls the stream abnormally, Agora recommends that you Delete that Converter and create a new Converter.	★★★★★
Please make sure that the sequence value is incremented when you Update the same Converter multiple times. Please refer to the sequence parameter explanation for details.	★★★★★
When there is an error in the request, please be sure to print out the X-Request-ID and X-Resource-ID field values of the response header in the log to facilitate troubleshooting.	★★★☆☆