# 调用转码 RESTful API (/zh-CN/realtime-media/transcoding/build/call-api)

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

## 前提条件 [#前提条件]

本文介绍声网 RESTful API 的构成，并引导你如何正确地调用 API。

在调用 RESTful API 之前，请确保已获取声网 App ID 和 Token（可选，用于安全鉴权）；对于服务端产品，还需要获取客户 ID 和客户密钥。可参考[开通转码服务](/zh-CN/realtime-media/transcoding/build/enable-service)。

## 配置 URL [#配置-url]

以[创建云端转码](/zh-CN/api-reference/api-ref/cloud-transcoding/create)为例，请求 URL 格式如下：

```text
https://api.sd-rtn.com/v1/projects/{appId}/rtsc/cloud-transcoder/tasks
```

其中：

- `https`：通信协议。声网使用 HTTPS 协议。

- `api.sd-rtn.com`：声网服务端域名。

- `v1/projects/{appid}/rtsc/cloud-transcoder/tasks/{taskId}`：资源路径。
  - `v1/projects`：API 版本和资源名。
  - `{appid}`：声网为每个开发者提供的 App ID，是项目的唯一标识。
  - `rtsc/cloud-transcoder`：代表声网产品或服务，此处为云端转码服务。
  - `tasks`：指定调用的接口，此处为云端转码任务相关接口。

以上示例仅作参考，你可以参照要调用的 API 的文档，在代码源文件或调试应用中先选择调用方法（如 GET、POST、PUT、PATCH、DELETE），然后根据 API 文档来配置实际的请求 URL。请求 URL 需要区分大小写。

## 发送请求 [#发送请求]

请求包括请求 Header 和请求 Body 两部分。在配置完 URL 后，你需要设置请求 Header 和 Body 信息，然后向服务器发送请求。

以下是[创建云端转码](/zh-CN/api-reference/api-ref/cloud-transcoding/create)的请求示例：

```shell
curl --location --request POST 'https://api.sd-rtn.com/v1/projects/<your_app_id>/rtsc/cloud-transcoder/tasks' \
--header 'Accept: application/json' \
--header 'Authorization: <http_basic_auth>' \
--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,
              }
            }
          ]
        }
      }
    }
  }
}'
```

本示例代表将 RTC 频道 `test01` 中的用户 `123` 和 `456` 进行混音和合图的转码处理，并将处理后的流输出到 `test01` 频道中，输出流的用户 ID 为 `1000`。混音和合图的转码输入流分别由 `audioInputs` 和 `videoInputs` 设置；转码输出流由 `outputs` 设置。该示例仅作参考，你可以参照要调用的 API 的文档，配置实际的请求头和包体信息。

### 请求 Header [#请求-header]

请求 Header 包含了处理请求所需要的信息，比如：

- `Accept`：告知服务器，客户端可以处理哪些类型的响应，如 `application/json`。
- `Authorization`：声网 RESTful API 要求 HTTP 鉴权。每次发送 HTTP 请求时，都必须在请求 Header 部填入 Authorization 字段。关于如何生成该字段的值，请参考[实现 HTTP 鉴权](/zh-CN/realtime-media/transcoding/build/http-auth)。
- `Content-Type`：指定请求体的类型为 `application/json` 。

### 请求 Body（可选） [#请求-body可选]

请求 Body 包含了要发送给服务器的数据。例如，创建一个新的云端转码任务，你需要在请求 Body 中包含转码的参数信息，如最大空闲时长、音视频输入源频道名、音视频输出属性等。详情可参考具体 API 文档的参数描述。请求 Body 需要区分大小写。

## 接收响应 [#接收响应]

在发送请求后，声网服务器会对你的请求进行响应。响应包括响应状态码、响应 Header 和响应 Body。

### 响应状态码 [#响应状态码]

响应的 HTTP 状态码分为 200 和非 200 两种情况，详情可参考[响应状态码](/zh-CN/realtime-media/transcoding/reference/response-code)。

- 如果返回的 HTTP 状态码为 200，表示请求成功。
- 如果 HTTP 状态码不为 200，参考响应状态码排查问题。

### 响应 Header（可选） [#响应-header可选]

响应 Header 指明了响应的标识，以区分不同请求所收到的响应。常见的响应 Header 包括：

- `X-Request-ID`，本次请求的 UUID（通用唯一识别码）。

### 响应 Body [#响应-body]

响应 Body 包含服务器返回的数据。例如，创建云端转码任务的响应 Body 包括用户 ID、云端播放器 ID、播放器创建的时间戳等信息。具体信息以每个 API 的返回值为准。

以下是[创建云端转码](/zh-CN/api-reference/api-ref/cloud-transcoding/create)的响应示例：

```json
{
  "taskId": "609f28f2644f1ae1ceb041b7047e3***",
  "createTs": 1661324613,
  "status": "STARTED",
  "services": {
    "cloudTranscoder": {
      "config": {},
      "createTs": 1661324614,
      "details": {},
      "message": "",
      "serviceType": "cloudTranscoderV2",
      "status": "serviceReady"
    }
  },
  "eventHandlers": {},
  "execution": {
    "workflows": {}
  },
  "properties": {},
  "sequenceId": "0",
  "variables": {},
  "workflows": {}
}
```

## 错误处理 [#错误处理]
当你遇到问题时，可以使用开发者工具查看请求和响应，结合[响应状态码](/zh-CN/realtime-media/transcoding/reference/response-code)进行排查。如未能解决问题，可联系[技术支持](https://ticket.shengwang.cn)。