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:
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 valueinfoObtain 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
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
Key fields:
taskId
: Use this to query task status or stop the transcoding taskstatus
: 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
.