# REST quickstart (/en/realtime-media/transcoding/rest-quickstart)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

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

## Prerequisites [#prerequisites]

Before you start, ensure that you have followed the [Enable Cloud Transcoding](manage-agora-account) 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 [#call-a-cloud-transcoding-rest-api]

This section walks you through creating a simple Cloud Transcoding task using the [Create RESTful API](/en/api-reference/cloud-transcoding/restful).

### Configure the request URL [#configure-the-request-url]

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

```html
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

    <CalloutContainer type="info">
      <CalloutDescription>
        Obtain the `builderToken` using the [Acquire API](/en/api-reference/cloud-transcoding/restful) before creating a task.
      </CalloutDescription>
    </CalloutContainer>

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

### Send the request [#send-the-request]

A typical API request includes:

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

#### Request headers [#request-headers]

| Header          | Description                                                                                             |
| --------------- | ------------------------------------------------------------------------------------------------------- |
| `Accept`        | Expected response format, e.g., `application/json`.                                                     |
| `Authorization` | Required for authentication. See [RESTful Authentication](/en/api-reference/cloud-transcoding/restful). |
| `Content-Type`  | Format of the request body, e.g., `application/json`.                                                   |

#### Request body [#request-body]

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

#### Request example [#request-example]

```bash
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 [#handling-the-response]

After sending a request, the server responds with:

* HTTP status code
* Response headers
* Response body

#### Response status codes [#response-status-codes]

| Code    | Meaning | Action                                              |
| ------- | ------- | --------------------------------------------------- |
| 200     | Success | Proceed as normal.                                  |
| Non-200 | Error   | See [HTTP status codes](../reference/status-codes). |

#### Response headers (Optional) [#response-headers-optional]

Common response headers include:

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

#### Example response [#example-response]

```json
{
  "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 [#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](../reference/status-codes) for specific error meanings

For persistent issues, contact [technical support](mailto\:support@agora.io) with your `X-Request-ID`.