Skip to main content

REST quickstart

This page explains how to call Agora Cloud Transcoding RESTful APIs to implement cloud transcoding in your app.

Prerequisites

Before you start, ensure that you have followed the Enable Cloud Transcoding guide to:

  • Set up your Agora account and activate the Cloud Transcoding service
  • Obtain your App ID from Agora Console
  • Obtain your Customer ID and Customer Secret for REST API authentication
  • Generate RTC tokens for your channels (valid for up to 24 hours)

Call a Cloud Transcoding REST API

This section walks you through creating a simple Cloud Transcoding task using the Create RESTful API.

Configure the request URL

Each RESTful API request follows a specific format. For example, the URL to create a transcoding task is:


_1
https://api.sd-rtn.com/v1/projects/:appId/rtsc/cloud-transcoder/tasks?builderToken=<actual_token_value>

URL structure:

  • https: Secure protocol.

  • api.sd-rtn.com: Agora’s server domain.

  • v1/projects/:appId/rtsc/cloud-transcoder/tasks: Resource path.

    • v1: API version.

    • :appId: Your Agora app ID.

    • rtsc/cloud-transcoder: The product or service name.

    • tasks: The endpoint you’re calling.

    • ?builderToken=<actual_token_value>: Query parameter and its value

      info

      Obtain the builderToken using the Acquire API before creating a task.

Refer to the specific API documentation for the correct HTTP method (GET, POST, PUT, PATCH, DELETE) and resource path.

Send the request

A typical API request includes:

  • A URL
  • Request headers
  • (Optional) A request body

Request headers

HeaderDescription
AcceptExpected response format, e.g., application/json.
AuthorizationRequired for authentication. See RESTful Authentication.
Content-TypeFormat of the request body, e.g., application/json.

Request body

The request body contains the parameters specific to the API, such as input and output configurations.

Request example


_86
curl --location --request POST 'https://api.sd-rtn.com/v1/projects/<your_app_id>/rtsc/cloud-transcoder/tasks?builderToken=<your_builder_token>' \
_86
--header 'Accept: application/json' \
_86
--header 'Authorization: Basic <base64_encoded_customer_credentials>'
_86
--header 'Content-Type: application/json' \
_86
--data '{
_86
"services": {
_86
"cloudTranscoder": {
_86
"serviceType": "cloudTranscoderV2",
_86
"config": {
_86
"transcoder": {
_86
"audioInputs": [
_86
{
_86
"rtc": {
_86
"rtcChannel": "test01",
_86
"rtcUid": 123,
_86
"rtcToken": "aab8b8f5a8cd4469a63042fcfafe7***"
_86
}
_86
},
_86
{
_86
"rtc": {
_86
"rtcChannel": "test01",
_86
"rtcUid": 456,
_86
"rtcToken": "aab8b8f5a8cd4469a63042fcfafe7***"
_86
}
_86
}
_86
],
_86
"canvas": {
_86
"width": 1280,
_86
"height": 720,
_86
"color": 255
_86
},
_86
"videoInputs": [
_86
{
_86
"rtc": {
_86
"rtcChannel": "test01",
_86
"rtcUid": 123,
_86
"rtcToken": "aab8b8f5a8cd4469a63042fcfafe7***"
_86
},
_86
"placeholderImageUrl": "https://example.jpg",
_86
"region": {
_86
"x": 0,
_86
"y": 0,
_86
"width": 480,
_86
"height": 360,
_86
"zOrder": 2
_86
}
_86
},
_86
{
_86
"rtc": {
_86
"rtcChannel": "test01",
_86
"rtcUid": 456,
_86
"rtcToken": "aab8b8f5a8cd4469a63042fcfafe7***"
_86
},
_86
"placeholderImageUrl": "https://example.jpg",
_86
"region": {
_86
"x": 0,
_86
"y": 240,
_86
"width": 480,
_86
"height": 360,
_86
"zOrder": 2
_86
}
_86
}
_86
],
_86
"outputs": [
_86
{
_86
"rtc": {
_86
"rtcChannel": "test02",
_86
"rtcUid": 1000,
_86
"rtcToken": "aab8b8f5a8cd4469a63042fcfafe7***"
_86
},
_86
"audioOption": {
_86
"profileType": "AUDIO_PROFILE_MUSIC_STANDARD"
_86
},
_86
"videoOption": {
_86
"fps": 15,
_86
"codec": "H264",
_86
"width": 1280,
_86
"height": 720
_86
}
_86
}
_86
]
_86
}
_86
}
_86
}
_86
}
_86
}'

This example mixes audio and combines video from users 123 and 456 in channel test01, and outputs the stream to test02 with user ID 1000.

Handling the response

After sending a request, the server responds with:

  • HTTP status code
  • Response headers
  • Response body

Response status codes

CodeMeaningAction
200SuccessProceed as normal.
Non-200ErrorSee HTTP status codes.

Response headers (Optional)

Common response headers include:

  • X-Request-ID: Unique request identifier for tracking/debugging.

Example response


_11
{
_11
"taskId": "609f28f2644f1ae1ceb041b7047e3***",
_11
"createTs": 1661324613,
_11
"status": "STARTED",
_11
"services": {
_11
"cloudTranscoder": {
_11
"serviceType": "cloudTranscoderV2",
_11
"status": "serviceReady"
_11
}
_11
}
_11
}

Key fields:

  • taskId: Use this to query task status or stop the transcoding task
  • status: Current task state

Troubleshoot

If a request fails:

  1. Check authentication: Verify your Customer ID and Customer Secret are correct
  2. Validate parameters: Ensure all required fields are included and properly formatted
  3. Check rate limits: Ensure you're not exceeding 10 requests per second
  4. Inspect the response: Use developer tools to examine the full error response
  5. Check status codes: Refer to HTTP status codes for specific error meanings

For persistent issues, contact technical support with your X-Request-ID.