Create a cloud transcoding task

POST

https://api.sd-rtn.com/v1/projects/{appId}/rtsc/cloud-transcoder/tasks

Use this endpoint to create a Cloud Transcoding task. When the task starts, the Agora server transcodes multiple input streams you specified and outputs them to the specified Agora RTC channel.

Request

Path parameters

appId stringrequired

The App ID of your project from Agora Console.

Query parameters

builderToken stringrequired

The tokenName you obtained in the response body of the Acquire method. See Acquire a builder token.

Request body

APPLICATION/JSON

BODYrequired

services objectrequired
Show propertiesHide properties
- cloudTranscoder objectrequired
  Show propertiesHide properties
  serviceType stringrequired
  The service type. Use "cloudTranscoderV2".
  config objectrequired
  Show propertiesHide properties
  transcoder objectrequired
  Show propertiesHide properties
  idleTimeout numbernullable
  Default: 300
  Possible values: 1 to 86400
  The maximum period (in seconds) that Cloud Transcoder can be idle. Idle means that all hosts corresponding to the audio and video streams processed by Cloud Transcoder have left the channel. If the idle state exceeds the set time, Cloud Transcoder is automatically destroyed.
  streamProcessMode stringnullable
  Default: mix
  If this parameter is not specified, the working mode of Cloud transcoder is the merge mode. You can specify the following modes:
  
  heterogeneous-single: Heterogeneous single stream mode. The types of input stream and output stream can be different or the same. The currently supported stream types are RTC and CDN.
  
  single: RTC stream relay mode. Relays the host's audio and video data and signaling in the source channel to the destination channel.
  
  info
  
  If you set streamProcessMode to heterogeneous-single or single, then the audioInputs or videoInputs list may contain at most one item.
  
  If you need to mix audio, combine images, or mix audio and combine images, no streamProcessMode settings are required.
  
  audioInputs arraynullable
  Audio input source list, supports two types: RTC audio stream and CDN audio stream. If you specify multiple input audio sources, the streams are mixed.
  info
  Either rtc or streamUrl must be filled in.
  Show propertiesHide properties
  streamUrl stringnullable
  The URL of the audio source stream. Required when the audio input source is CDN.
  volume numbernullable
  Default: 100
  Possible values: 0 to 200
  The volume of the audio source stream. This parameter only takes effect when the audio input source is CDN.
  repeat numbernullable
  Default: 1
  The number of times to play the media stream. This parameter only takes effect when the audio input source is CDN.
  
  1: Play the media stream once.
  
  -1: Play the media stream in a loop.
  
  n: Specify the number of times to play the media stream. Cannot be set to 0.
  
  rtc objectnullable
  When the audio input source is RTC, this object is required.
  Show propertiesHide properties
  rtcChannel stringrequired
  The RTC channel name for the audio input source. Currently, only audio and video sources that subscribe to a single channel are supported. The audio source and video source must belong to the same channel.
  rtcUid numberrequired
  The UID corresponding to the audio input source. The same UID must not exist in the RTC channel.
  rtcToken stringrequired
  The token that the Cloud Transcoder uses to join the RTC channel for transcoding. Using a token ensures channel security and prevents malicious users from disrupting other users in the channel. See Token authentication for details.
  The UID of Cloud Transcoder in the RTC channel is randomly assigned by Agora. Therefore, when generating a token, set the uid to 0.
  videoInputs arraynullable
  Video input source list, supports RTC video stream and CDN video stream. If you specify multiple input video sources, the streams are merged.
  Show propertiesHide properties
  streamUrl stringnullable
  The URL of the video source stream. Required when the video input source is CDN.
  repeat numbernullable
  Default: 1
  The number of times to play the media stream. This parameter only takes effect when the input source is CDN.
  
  1: Play the media stream once.
  
  -1: Play the media stream in a loop.
  
  n: Specify the number of times to play the media stream. Cannot be set to 0.
  
  rtc objectnullable
  This object is required when the video input source is RTC.
  Show propertiesHide properties
  rtcChannel stringrequired
  The RTC channel name for the video input source. Currently, only audio and video sources that subscribe to a single channel are supported. The audio source and video source must belong to the same channel.
  rtcUid numberrequired
  The UID corresponding to the video input source. The same UID must not exist in the RTC channel.
  rtcToken stringrequired
  The token that the Cloud Transcoder uses to join the RTC channel for transcoding. Using a token ensures channel security and prevents malicious users from disrupting other users in the channel. See Token authentication for details.
  The UID of Cloud Transcoder in the RTC channel is randomly assigned by Agora. Therefore, when generating a token, set the uid to 0.
  placeholderImageUrl stringnullable
  The URL of the placeholder image displayed when the user is offline. It must be a valid image URL and contain the jpg or png suffix.
  region objectrequired
  Show propertiesHide properties
  x numberrequired
  Possible values: 0 to 3840
  The x coordinate of the image on the canvas (px). The x coordinate is the horizontal displacement of the upper left corner of the image relative to the origin, where the upper left corner of the canvas is the origin.
  y numberrequired
  Possible values: 0 to 3840
  The y coordinate of the image on the canvas (px). The y coordinate is the vertical displacement of the upper left corner of the image relative to the origin, where the upper left corner of the canvas is the origin.
  width numberrequired
  Possible values: 120 to 3840
  The width of the screen (px).
  height numberrequired
  Possible values: 120 to 3840
  The height of the screen (px).
  zOrder numberrequired
  Possible values: 2 to 100
  The layer order of the host screen. 2 represents the layer above the placeholder layer. 100 represents the top layer.
  canvas objectrequired
  Show propertiesHide properties
  width numberrequired
  Possible values: 120 to 3840
  The width of the canvas (px).
  height numberrequired
  Possible values: 120 to 3840
  The height of the canvas (px).
  color numberrequired
  Possible values: 0 to 16777215
  The background color of the canvas. The RGB color value represented as a decimal number
  backgroundImage stringnullable
  Canvas background image. Must be a valid image URL with a jpg or png suffix. If omitted, there is no canvas background image.
  fillMode stringnullable
  Default: "FILL"
  Fill mode for the canvas background image:
  
  "FILL": Scale the image and crop it in the center while maintaining the aspect ratio.
  
  "FIT": Scale the image to fill the display while maintaining the aspect ratio.
  
  watermarks arrayrequired
  Show propertiesHide properties
  imageUrl stringrequired
  The URL of the watermark image. It must be a valid URL with a jpg or png suffix.
  region objectrequired
  Show propertiesHide properties
  x numberrequired
  Possible values: 0 to 3840
  The x coordinate of the watermark on the canvas (px). The x coordinate is the horizontal displacement of the upper left corner of the image relative to the origin.
  y numberrequired
  Possible values: 0 to 3840
  The y coordinate of the watermark on the canvas (px). The y coordinate is the vertical displacement of the upper left corner of the image relative to the origin.
  width numberrequired
  Possible values: 120 to 3840
  The width of the watermark (px).
  height numberrequired
  Possible values: 120 to 3840
  The height of the watermark (px).
  zOrder numberrequired
  Possible values: 0 to 100
  The layer order of the watermark. 0 represents the bottom layer. 100 represents the top layer.
  fillMode stringnullable
  Default: "FILL"
  Watermark fill mode:
  
  "FILL": Scale the image and crop it in the center while maintaining the aspect ratio.
  
  "FIT": Scale the image to fill the display while maintaining the aspect ratio.
  
  outputs arrayrequired
  Configure output settings to publish to an RTC channel or CDN address.
  You must specify either streamUrl or rtc.
  Show propertiesHide properties
  streamUrl stringnullable
  CDN streaming address.
  rtc objectrequired
  Required for publishing to an RTC channel.
  Show propertiesHide properties
  rtcChannel stringrequired
  The RTC channel name for the transcoded audio and video.
  rtcUid numberrequired
  The UID of the RTC channel for the transcoded audio and video streams. Make sure this value is different from the UID of other users in the channel.
  rtcToken stringrequired
  The token that the Cloud Transcoder uses to join the output RTC channel. Using a token ensures channel security and prevents malicious users from disrupting other users in the channel. See Token authentication for details.
  When generating this token, use outputs.rtc.rtcUid to generate the token.
  audioOption objectnullable
  Show propertiesHide properties
  profileType stringnullable
  Default: AUDIO_PROFILE_DEFAULT
  Audio properties of the transcoded output:
  
  "AUDIO_PROFILE_DEFAULT": 48 kHz sampling rate, music encoding, mono channel, maximum encoding bitrate is 64 Kbps.
  
  "AUDIO_PROFILE_SPEECH_STANDARD": 32 kHz sampling rate, speech encoding, mono channel, maximum encoding bitrate is 18 Kbps.
  
  "AUDIO_PROFILE_MUSIC_STANDARD": 48 KHz sampling rate, music encoding, mono channel, maximum encoding bitrate is 64 Kbps.
  
  "AUDIO_PROFILE_MUSIC_STANDARD_STEREO": 48 KHz sampling rate, music encoding, stereo channel, maximum encoding bitrate is 80 Kbps.
  
  "AUDIO_PROFILE_MUSIC_HIGH_QUALITY": 48 KHz sampling rate, music encoding, mono channel, maximum encoding bitrate is 96 Kbps.
  
  "AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO": 48 kHz sampling rate, music encoding, dual channels, and a maximum encoding bitrate of 128 Kbps.
  
  videoOption objectnullable
  Show propertiesHide properties
  width numberrequired
  Possible values: 120 to 3840
  The width of the transcoded output video (px).
  height numberrequired
  Possible values: 120 to 3840
  The height of the transcoded output video (px).
  bitrate numberrequired
  Possible values: 1 to 10000
  The bitrate of the transcoded output video.
  codec stringrequired
  The codec used to transcode the output video.
  Possible values:
  
  "H264": Standard H.264 encoding.
  
  "VP8": Standard VP8 encoding.
  
  fps numbernullable
  Default: 15
  Possible values: 1 to 30
  The frame rate (fps) of the transcoded output video.
  mode stringnullable
  Can be set to RAW, which means the output video is not transcoded. The encoding format of the input video remains unchanged.
  If the output video is transcoded, do not set this field. In RAW mode, the number of inputs set in videoInputs can only be 1.

Response

Response header

X-Request-ID stringnullable

UUID (Universally Unique Identifier), used to identify this request.

If the request fails, print out the value in the log to troubleshoot the problem. If the response status code of the request is not 2XX, then the response header may not contain this field.

Response body

If the returned status code is 200, the request was successful. The response body contains the result of the request.
OK
- taskId string
  A UUID used to identify the cloud transcoder for this request operation.
- createTs number
  Unix timestamp (seconds) when the transcoding task was created.
- status string
  The running status of the transcoding task:
  
  "IDLE": Task not started.
  
  "PREPARED": The task has received a start request.
  
  "STARTING": The task is starting.
  
  "CREATED": Task initialization completed.
  
  "STARTED": The task has started.
  
  "IN_PROGRESS": Task in progress.
  
  "STOPPING": The task is stopping.
  
  "STOPPED": The task has stopped.
  
  "EXIT": The task exited normally.
  
  "FAILURE_STOP": The task exited abnormally.
- services object
  Show propertiesHide properties
  cloudTranscoder object
  Show propertiesHide properties
  config object
  Same as the fields you set in the Create request body.
  createTs number
  Unix timestamp (in seconds) when the service was created.
  details object
  Reserved field.
  message string
  Reserved field.
  serviceType string
  Should be "cloudTranscoderV2".
  status string
  The running status of the transcoding service in the transcoding task:
  
  "serviceIdle": The service has not started.
  
  "serviceReady": The service is ready to start.
  
  "serviceStarted": The service has started.
  
  "serviceInProgress": The service is currently running.
  
  "serviceCompleted": The service has stopped, and all tasks have been completed.
  
  "servicePartialCompleted": The service has stopped, but the task was only partially completed.
  
  "serviceValidationFailed": The service failed due to invalid parameters.
  
  "serviceAbnormal": The service exited unexpectedly.
  
  "serviceUnknown": The service status is unknown.
  
  This field is meant for the Agora technical team to investigate any issues. You do not need to focus on it.
  eventHandlers object
  Reserved field.
  execution object
  Show propertiesHide properties
  workflows object
  Reserved field.
  properties object
  Reserved field.
  sequenceId string
  Reserved field.
  variables object
  Reserved field.
  workflows object
  Reserved field.
If the returned status code is not 200, the request failed.
Non 200
- message string
  Describes why the request failed.

Reference

After calling the Acquire method successfully, you receive a builderToken in the response body. You can use a builderToken for a single cloud transcoding task.
The validity period of a builderToken for creating cloud transcoding is 5 minutes. However, to ensure successful cloud transcoding, best practice is to initiate the corresponding Create request within 2 seconds after each Acquire response is received.
Making batch Create requests after batch builderToken requests may cause the request to fail.

Authorization

This endpoint requires Basic Auth.

Request example

curl
Python
Node.js

curl --request post \
  --url 'https://api.sd-rtn.com/v1/projects/:appId/rtsc/cloud-transcoder/tasks?builderToken=<actual_token_value>' \
  --header 'Authorization: Basic <credentials>' \
  --header 'Content-Type: <string>' \
  --data '
{
  "services": {
    "cloudTranscoder": {
      "serviceType": "cloudTranscoderV2",
      "config": {
        "transcoder": {
          "idleTimeout": 300,
          "audioInputs": [
            {
              "rtc": {
                "rtcChannel": "test01",
                "rtcUid": 123,
                "rtcToken": "aab8b8f5a8cd4469a63042fcfafe7***"
              }
            },
            {
              "rtc": {
                "rtcChannel": "test01",
                "rtcUid": 456,
                "rtcToken": "aab8b8f5a8cd4469a63042fcfafe7***"
              }
            }
          ],
          "canvas": {
            "width": 960,
            "height": 480,
            "color": 0,
            "backgroundImage": "https://example.jpg",
            "fillMode": "FIT"
          },
          "waterMarks": [
            {
              "imageUrl": "https://example.png",
              "region": {
                "x": 0,
                "y": 0,
                "width": 120,
                "height": 120,
                "zOrder": 50
              }
            }
          ],
          "videoInputs": [
            {
              "rtc": {
                "rtcChannel": "test01",
                "rtcUid": 123,
                "rtcToken": "aab8b8f5a8cd4469a63042fcfafe7***"
              },
              "placeholderImageUrl": "https://example.jpg",
              "region": {
                "x": 0,
                "y": 0,
                "width": 320,
                "height": 360,
                "zOrder": 2
              }
            },
            {
              "rtc": {
                "rtcChannel": "test01",
                "rtcUid": 456,
                "rtcToken": "aab8b8f5a8cd4469a63042fcfafe7***"
              },
              "placeholderImageUrl": "https://example.jpg",
              "region": {
                "x": 320,
                "y": 0,
                "width": 320,
                "height": 320,
                "zOrder": 2
              }
            }
          ],
          "outputs": [
            {
              "rtc": {
                "rtcChannel": "test",
                "rtcUid": 1000,
                "rtcToken": "aab8b8f5a8cd4469a63042fcfafe7***"
              },
              "audioOption": {
                "profileType": "AUDIO_PROFILE_MUSIC_STANDARD"
              },
              "videoOption": {
                "fps": 30,
                "codec": "H264",
                "bitrate": 800,
                "width": 960,
                "height": 480
              }
            }
          ]
        }
      }
    }
  }
}'

Response example

200
Non-200

{
  "createTs": 1661324613,
  "eventHandlers": {},
  "execution": {
    "workflows": {}
  },
  "properties": {},
  "sequenceId": "0",
  "services": {
    "cloudTranscoder": {
      "config": {},
      "createTs": 1661324614,
      "details": {},
      "message": "",
      "serviceType": "cloudTranscoderV2",
      "status": "serviceReady"
    }
  },
  "status": "STARTED",
  "taskId": "609f28f2644f1ae1ceb041b7047e3***",
  "variables": {},
  "workflows": {}
}