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
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
200application/jsonThe 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.
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": {}}{ "message": "Describes why the request failed."}