Create a cloud transcoding task
Updated
Creates a Cloud Transcoding task for specified input streams.
https://api.sd-rtn.com/v1/projects/{appId}/rtsc/cloud-transcoder/tasksUse 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.
Path Parameters
The App ID of your project from Agora Console.
Query Parameters
The tokenName you obtained in the response body of the Acquire method. See Acquire a builder token.
Header Parameters
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.
Request Body
application/json
Should be "cloudTranscoderV2".
The service type. Use "cloudTranscoderV2".
cloudTranscoderV2Same as the fields you set in the Create request body.
The maximum period, in seconds, that Cloud Transcoder can be idle. If the idle state exceeds this value, Cloud Transcoder is automatically destroyed.
300[1, 86400]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.
Note
-
If you set
streamProcessModetoheterogeneous-singleorsingle, then theaudioInputsorvideoInputslist may contain at most one item. -
If you need to mix audio, combine images, or mix audio and combine images, no
streamProcessModesettings are required.
mixmix | heterogeneous-single | singleAudio input source list, supports two types: RTC audio stream and CDN audio stream. If you specify multiple input audio sources, the streams are mixed.
Note
Either rtc or streamUrl must be filled in.
The URL of the audio source stream. Required when the audio input source is CDN.
The volume of the audio source stream. This parameter only takes effect when the audio input source is CDN.
100[0, 200]The number of times to play the media stream. 1 means play once, -1 means loop, and any positive integer specifies a playback count.
1When the audio input source is RTC, this object is required.
The RTC channel name for the transcoded audio and video.
The RTC channel name for the audio input source. Currently, you can only subscribe to audio and video sources from a single channel; the audio and video sources must belong to the same channel.
The RTC channel name for the video input source. Currently, you can only subscribe to audio and video sources from a single channel; the audio and video sources must belong to the same channel.
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.
The UID corresponding to the audio input source. The same UID must not exist in the RTC channel.
The UID corresponding to the video input source. The same UID must not exist in the RTC channel.
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.
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.
Video input source list, supports RTC video stream and CDN video stream. If you specify multiple input video sources, the streams are merged.
The URL of the video source stream. Required when the video input source is CDN.
The number of times to play the media stream. 1 means play once, -1 means loop, and any positive integer specifies a playback count.
1This object is required when the video input source is RTC.
The RTC channel name for the transcoded audio and video.
The RTC channel name for the audio input source. Currently, you can only subscribe to audio and video sources from a single channel; the audio and video sources must belong to the same channel.
The RTC channel name for the video input source. Currently, you can only subscribe to audio and video sources from a single channel; the audio and video sources must belong to the same channel.
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.
The UID corresponding to the audio input source. The same UID must not exist in the RTC channel.
The UID corresponding to the video input source. The same UID must not exist in the RTC channel.
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.
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.
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.
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.
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.
[0, 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.
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.
[0, 3840]The height of the watermark (px).
The height of the screen (px).
[120, 3840]The layer order of the watermark. 0 represents the bottom layer. 100 represents the top layer.
The layer order of the host screen. 2 represents the layer above the placeholder layer. 100 represents the top layer.
[2, 100]Canvas background image. Must be a valid image URL with a jpg or png suffix. If omitted, there is no canvas background image.
Watermark list.
The URL of the watermark image.
The layer order of the watermark. 0 represents the bottom layer. 100 represents the top layer.
The layer order of the host screen. 2 represents the layer above the placeholder layer. 100 represents the top layer.
[2, 100]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.
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.
[0, 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.
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.
[0, 3840]The height of the watermark (px).
The height of the screen (px).
[120, 3840]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.
FILLFILL | FITConfigure output settings to publish to an RTC channel or CDN address.
You must specify either streamUrl or rtc.
Configure output settings to publish to a single RTC channel or CDN address.
You must specify either streamUrl or rtc.
CDN streaming address.
Required for publishing to an RTC channel. Currently, you can publish to only one RTC channel.
The RTC channel name for the transcoded audio and video.
The RTC channel name for the audio input source. Currently, you can only subscribe to audio and video sources from a single channel; the audio and video sources must belong to the same channel.
The RTC channel name for the video input source. Currently, you can only subscribe to audio and video sources from a single channel; the audio and video sources must belong to the same channel.
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.
The UID corresponding to the audio input source. The same UID must not exist in the RTC channel.
The UID corresponding to the video input source. The same UID must not exist in the RTC channel.
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.
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.
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.
AUDIO_PROFILE_DEFAULTAUDIO_PROFILE_DEFAULT | AUDIO_PROFILE_SPEECH_STANDARD | AUDIO_PROFILE_MUSIC_STANDARD | AUDIO_PROFILE_MUSIC_STANDARD_STEREO | AUDIO_PROFILE_MUSIC_HIGH_QUALITY | AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREOThe codec used to transcode the output video.
Possible values:
"H264": Standard H.264 encoding."VP8": Standard VP8 encoding.
H264 | H265Can 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.
Whether to enable low-bitrate high-quality mode.
Response
-
If the returned status code is
200, the request was successful. The response body contains the result of the request. -
If the returned status code is not
200, the request failed.
Response Body
application/json
application/json
Response schema
200The request succeeded and returned task information.
A UUID used to identify the cloud transcoder for this request operation.
Unix timestamp (seconds) when the transcoding task was created.
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.
The sequence ID.
Same as the fields you set in the Create request body.
Unix timestamp (in seconds) when the service was created.
Reserved field.
Reserved field.
Should be "cloudTranscoderV2".
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.
Response Headers
The unique request ID. If the request fails, use this value in the log to troubleshoot the problem.
200Reference
Note the following guidelines when using a builderToken:
- After calling the
Acquire a builder tokenendpoint successfully, you receive abuilderTokenin the response body. You can use abuilderTokenfor a single Cloud Transcoding task. - The validity period of a
builderTokenfor creating Cloud Transcoding is 5 minutes. To ensure successful Cloud Transcoding, best practice is to initiate the correspondingCreaterequest within 2 seconds after eachAcquireresponse is received. - Making batch
Createrequests after batchbuilderTokenrequests may cause the request to fail.
Output destination constraints
- A single transcoding task cannot push to both a CDN address and an RTC channel simultaneously. To push to both destinations, create two separate tasks.
- If the audio or video configurations differ between the two destinations, create two separate tasks.
- To push to multiple CDN addresses, include all destination addresses within a single
outputsobject. - Each transcoding task can push to only one RTC channel. To push to two different RTC channels, create two separate tasks.
Request examples
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
{ "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": {}}