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:

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

Header	Description
`Accept`	Expected response format, e.g., `application/json`.
`Authorization`	Required for authentication. See RESTful Authentication.
`Content-Type`	Format 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

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

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

Code	Meaning	Action
200	Success	Proceed as normal.
Non-200	Error	See HTTP status codes.

Response headers (Optional)

Common response headers include:

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

Example response

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

Key fields:

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

Troubleshoot

If a request fails:

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

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