Skip to main content

You are viewing Agora Docs forBeta products and features. Switch to Docs

Use RESTful API

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

Authentication

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.

Understand the tech

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.

Create: Create a Converter

HTTP request


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

Path parameter

  • 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.
  • Query parameters

    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}

    Request header

    • 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:

    1654595558221

    Details for these fields are shown in the following table:

    FieldTypeDescriptions
    name(Optional) StringThe 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 ObjectThe 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) StringThe 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 ObjectThe 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 ObjectThe 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 ObjectThe video canvas. See canvas for details.
    transcodeOptions.videoOptions.layoutType(Optional) NumberThe 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 ArrayThe 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 elementNoneThe video screen of each user on the canvas. See RtcStreamView for details.
    transcodeOptions.videoOptions.layout.ImageView elementNoneThe video image on the canvas, which can be used as a watermark. See ImageView for details.
    transcodeOptions.videoOptions.vertical(Optional) JSON ObjectVertical layout. This parameter must be set when layoutType is 1. See vertical for details.
    transcodeOptions.videoOptions.defaultPlaceholderImageUrl(Optional) StringThe 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) NumberThe encoding bitrate (Kbps) of the video. The value range is [1,10000].
    transcodeOptions.videoOptions.gop(Optional) NumberThe GOP of the video. The defalt value is the value of frameRate * 2。
    transcodeOptions.videoOptions.frameRate(Optional) NumberThe encoding frame rate (fps) of the video. The value range is [1,30]. The default value is 15.
    transcodeOptions.videoOptions.codec(Optional) StringThe video codec type of the output video stream. The following values are supported:
  • (Default) H.264
  • H.265
  • transcodeOptions.videoOptions.codecProfile(Optional) StringThe 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.seiOptionsJSON ObjectSets 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) StringThe address of Media Push. It must be a valid RTMP address with a length of 1,024 characters or less.
    idleTimeOut(Optional) NumberThe 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) IntNetwork 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:

    FieldCategoryDescription
    nameStringThe name of the Converter.
    rawOptions(Required)JSON ObjectMedia Push configuration for the Converter.
    rawOptions.rtcChannelStringThe Agora channel name. The channel to which the stream processed by the Converter belongs.
    rawOptions.rtcStreamUidNumberThe UID of the user to which the media stream belongs.
    rtmpUrl(Required)StringThe CDN streaming address.
    idleTimeOutNumberThe 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) IntNetwork 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.
  • HTTP response

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

    Response header

    • 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.

    Response body

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

    img

    Details for these fields are shown in the following table:

    FieldTypeDescriptions
    idStringThe ID of the Converter. This is a UUID (Universal Unique Identifier) generated by the Agora server to identify a created Converter.
    createTsNumberThe Unix timestamp(seconds) when the Converter was created.
    updateTsNumberThe Unix timestamp(seconds) when the Converter configuration was last updated.
    stateStringThe running status of the Converter:
  • 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.
  • fieldsStringThe 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
    }

    Request example

    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
    }

    Response example


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

    Delete: Destroy the Converter

    HTTP request


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

    Path parameter

    • 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.

    Request header

    • 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.

    HTTP response

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

    Response header

    • 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.

    Response body

    • 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.

    Update: Update the Converter

    HTTP request


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

    Path parameter

    • 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.

    Query Parameters

    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}

    Request header

    • 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

    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.
  • HTTP response

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

    Response header

    • 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.

    Response body

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

    img

    Details of these fields are shown in the following table:

    FieldTypeDescriptions
    idStringThe ID of the Converter. This is a UUID (Universal Unique Identifier) generated by the Agora server to identify a created Converter.
    createTsNumberThe Unix timestamp(seconds) when the Converter was created.
    updateTsNumberThe Unix timestamp(seconds) when the Converter configuration was last updated.
    stateStringThe running status of the Converter:
  • 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.
  • fieldsStringThe 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.

    Request example

    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
    }

    Response example


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

    Get: Get the streaming status of the Converter

    HTTP request


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

    Path parameter

    • 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.

    Request header

    • 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.

    HTTP response

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

    Response header

    • 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.

    Response body

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

    1646374583131

    Details of these fields are shown in the following table:

    FieldTypeDescriptions
    nameStringThe name of the Converter.
    transcodeOptionsJSON ObjectThe transcoding configuration of the Converter.
    transcodeOptions.rtcChannelStringThe Agora channel name.
    transcodeOptions.audioOptionsJSON ObjectThe audio transcoding configuration of the Converter. See audioOptions for details.
    transcodeOptions.videoOptionsJSON ObjectThe video transcoding configuration of the Converter.
    transcodeOptions.videoOptions.canvasJSON ObjectThe video canvas. See canvas for details.
    transcodeOptions.videoOptions.layoutJSON ArrayThe content description of the video screen on the canvas. Two elements are supported: RtcStreamView and ImageView.
    transcodeOptions.videoOptions.layout.RtcStreamView elementNAThe video screen of each user on the canvas. See RtcStreamView for details.
    transcodeOptions.videoOptions.layout.ImageView elementNAThe video image on the canvas, which can be used as a watermark. See ImageView for details.
    transcodeOptions.videoOptions.bitrateNumberThe encoding bitrate (Kbps) of the video.
    transcodeOptions.videoOptions.frameRateNumberThe encoding frame rate (fps) of the video.
    transcodeOptions.videoOptions.codecStringThe video codec type of the output video stream.
    transcodeOptions.videoOptions.codecProfileStringThe encoding specification of the video.
    transcodeOptions.videoOptions.seiOptionsJSON ObjectThe user SEI information carried in the output video stream. See seiOptions for details.
    rtmpUrlStringThe address of Media Push.
    idleTimeoutNumberThe 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.
    createTsNumberThe Unix timestamp(seconds) when the Converter was created.
    stateStringThe running status of the Converter:
  • 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 nameCategoryDescription
    nameStringThe name of the Converter.
    rawOptionsJSON ObjectMedia Push configuration for the Converter.
    rawOptions.rtcChannelStringThe Agora channel name. The channel to which the stream processed by the Converter belongs.
    rawOptions.rtcStreamUidNumberThe UID of the user to which the media stream belongs.
    rtmpUrlStringThe CDN streaming address.
    idleTimeOutNumberThe 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.

    Response example

    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
    }

    List: Query the Converters of all or specified channels under a project

    HTTP request

    • 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

    Path parameter

    • 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

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

    Query Parameters

    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}

    Request header

    • 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.

    HTTP response

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

    Response header

    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.

    Response body

    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:

    FieldTypeDescriptions
    successBoolThe request was successful.
    dataJSON ObjectReturns data details.
    data.total_countStringThe number of all Converters under the queried project or channel.
    data.cursorJSONCursor 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.rtcChannelStringThe Agora channel name. This is the channel to which the stream processed by the Converter belongs.
    data.members.converterNameStringThe name of the Converter.
    data.members.updateTsNumberThe Unix timestamp(seconds) when the Converter configuration was last updated.
    data.members.appIdStringThe 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.rtmpUrlStringThe CDN streaming address.
    data.members.converterIdStringThe ID of the Converter. The unique identifier for the Converter.
    data.members.createNumberThe Unix timestamp(seconds) when the Converter was created.
    data.members.idleTimeoutNumberThe 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.stateStringThe running status of the Converter:
  • connecting: Connecting to the Agora streaming server and the CDN server.
  • running: Pushing the stream.
  • failed: Failed to push the stream.
  • Response example


    _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
    }

    API call rate limits

    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.

    APIRate limits
    CreateIn a project, the rate limit for the rate of creating a Converter is 50 times per second.
    DeleteIn a project, the rate limit for the converter destruction is 50 times per second.
    UpdateIn a project, the rate limit for the rate of updating a specified Converter is 2 times per second.
    GetIn 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 codesPossible message field content
    200 OK/
    400 Bad Request
  • Invalid parameter: rtmpUrl. Replace it, and retry.
  • Invalid parameter: idleTimeout. Replace it, and retry.
  • 401 UnauthorizedInvalid authentication credentials.
    403 ForbiddenThe project lacks permission to use this function. Contact Agora technical support.
    404 Not FoundResource cannot be found/has been destroyed.
    409 ConflictResource with the same name already exists. Use the existing resource; otherwise, delete it, and create a new resource.
    429 Too Many RequestsRequest rate limit exceeded.Resource quota limit exceeded.No available resources.
    500 UnknownInternal errors. Contact Agora for assistance with troubleshooting.
    501 Not ImplementedThe method requested has not been implemented.
    503 Service UnavailableThe 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 TimeoutGateway timeout. Check whether the resource is created; if not, re-create a new resource.

    Consideration

    This section summarizes the basic considerations for using the Media Push RESTful API:

    • Please make sure that the Agora channel profile is live broadcasting.
    • In case of request errors, make sure to print the values of the X-Request-ID and X-Resource-ID fields in the response header for troubleshooting.
    • As explained in the name description, you should use the name parameter if only one Converter is needed in a channel.
    • Set the region parameter to the region associated with the CDN source, as explained in the region parameter description.
    • If the Converter is automatically destroyed due to a service failure or other reasons, Agora recommends that you create a new Converter.
    • If the CDN side's pulling stream is abnormal after creating a Converter, Agora recommends that you delete the Converter and create a new one.
    • When updating the same Converter multiple times, ensure that the sequence value is incremented, as explained in the sequence parameter description.
    • Agora does not support performing both transcoding and non-transcoding live streaming in the same Converter. To use a different streaming mode, create a new Converter and configure it accordingly.
    • In non-transcoding mode, the Converter can only forward video streams with RTMP, not transcode video streams. To ensure that CDN audiences can watch the video, use video codec formats that comply with the RTMP standard protocol, such as H.264 or H.265. If the video codec format at the streaming end is VP8, use the Converter's transcoding mode.

    For more integration recommendations, see Integration Best Practices.

    Commonly used video profile

    Agora recommends that you use the default values when setting the video resolution, frame rate, and bitrate of the output transcoded stream. You can also refer to the following table to set the values. If you set a bitrate beyond a reasonable range, the Agora server automatically adjusts the bitrate to stay within a reasonable range.

    ResolutionFrame rate (fps)Bitrate (Kbps)
    160 × 12015130
    120 × 12015100
    320 × 18015280
    180 × 18015200
    240 × 18015240
    320 × 24015400
    240 × 24015280
    424 × 24015440
    640 × 36015800
    360 × 36015520
    640 × 360301200
    360 × 36030800
    480 × 36015640
    480 × 36030980
    640 × 480151000
    480 × 48015800
    640 × 480301500
    480 × 480301200
    848 × 480151220
    848 × 480301860
    640 × 48010800
    1280 × 720152260
    1280 × 720303420
    960 × 720151820
    960 × 720302760
    vundefined