Acquire a builder token
Updated
Acquires a builder token for creating a Cloud Transcoding task.
https://api.sd-rtn.com/v1/projects/{appId}/rtsc/cloud-transcoder/builderTokensBefore you create a Cloud Transcoding task, call the builderTokens endpoint to retrieve a builder token.
Path Parameters
The App ID of your project from Agora Console.
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 a builder token.
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 this endpoint successfully, you receive a
builderTokenin 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/builderTokens \ --header 'Authorization: Basic <credentials>' \ --header 'Content-Type: <string>' \ --data ' { "instanceId": "abc13328", "services": { "cloudTranscoder": { "serviceType": "cloudTranscoderV2", "config": { "transcoder": { "idleTimeout": 300, "audioInputs": [ { "rtc": { "rtcChannel": "test01", "rtcUid": 123, "rtcToken": "<your_rtc_token>" } }, { "rtc": { "rtcChannel": "test01", "rtcUid": 456, "rtcToken": "<your_rtc_token>" } } ], "canvas": { "width": 960, "height": 480, "color": 0, "backgroundImage": "https://web-cdn.agora.io/website-files/images/new-home-2-banne-online-karaoke-bg.jpg", "fillMode": "FIT" }, "waterMarks": [ { "imageUrl": "https://web-cdn.agora.io/website-files/images/advantage-interactive-live-streaming.png", "region": { "x": 0, "y": 0, "width": 100, "height": 100, "zOrder": 50 } } ], "videoInputs": [ { "rtc": { "rtcChannel": "test01", "rtcUid": 123, "rtcToken": "<your_rtc_token>" }, "placeholderImageUrl": "https://web-cdn.agora.io/website-files/images/new-home-2-banner-realtime-bg.jpg", "region": { "x": 0, "y": 0, "width": 320, "height": 360, "zOrder": 2 } }, { "rtc": { "rtcChannel": "test01", "rtcUid": 456, "rtcToken": "<your_rtc_token>" }, "region": { "x": 320, "y": 0, "width": 320, "height": 320, "zOrder": 2 } } ], "outputs": [ { "rtc": { "rtcChannel": "test02", "rtcUid": 1000, "rtcToken": "<your_rtc_token>" }, "audioOption": { "profileType": "AUDIO_PROFILE_MUSIC_STANDARD" }, "videoOption": { "fps": 30, "codec": "H264", "bitrate": 800, "width": 960, "height": 48 } } ] } } } } }'Response example
{ "createTs": 1661324606, "instanceId": "abc13328", "tokenName": "xUwUbQf9ZxxxxxtLslGnDg0lk8RYaUE0***"}{ "message": "Describes why the request failed."}