如何调用 API
本文介绍声网 RESTful API 的构成，并引导你如何正确地调用 API。
前提条件
在调用 RESTful API 之前，请确保已获取声网 App ID 和 Token（可选，用于安全鉴权）；对于服务端产品，还需要获取客户 ID 和客户密钥。可参考开通服务。
配置 URL
以创建云端转码为例，请求 URL 格式如下：
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 需要区分大小写。
发送请求
请求包括请求头和请求包体两部分。在配置完 URL 后，你需要设置请求头和包体信息，然后向服务器发送请求。
以下是创建云端转码的请求示例：
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 的文档，配置实际的请求头和包体信息。
请求头
请求头包含了处理请求所需要的信息，比如：
Accept：告知服务器，客户端可以处理哪些类型的响应，如application/json。Authorization：声网 RESTful API 要求 HTTP 认证。每次发送 HTTP 请求时，都必须在请求 Header 部填入 Authorization 字段。关于如何生成该字段的值，请参考实现 HTTP 安全认证。Content-Type：指定请求体的类型为application/json。
请求包体（可选）
请求包体包含了要发送给服务器的数据。例如，创建一个新的云端转码任务，你需要在请求包体中包含转码的参数信息，如最大空闲时长、音视频输入源频道名、音视频输出属性等。详情可参考具体 API 文档的参数描述。请求包体需要区分大小写。
接收响应
在发送请求后，声网服务器会对你的请求进行响应。响应包括响应状态码、响应头和响应体。
响应状态码
响应的 HTTP 状态码分为 200 和非 200 两种情况，详情可参考响应状态码。
- 如果返回的 HTTP 状态码为 200，表示请求成功。
- 如果 HTTP 状态码不为 200，参考响应状态码排查问题。
响应头（可选）
响应头指明了响应的标识，以区分不同请求所收到的的响应。常见的响应头包括：
X-Request-ID，本次请求的 UUID（通用唯一识别码）。
响应包体
响应包体包含了服务器返回的数据。例如，创建云端播放器的响应包体包括用户 UID、云端播放器 ID、播放器创建的时间戳等信息。具体信息以每个 API 的返回值为准。
以下是创建云端转码的响应示例：
{
"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": {}
}