# 调用转码 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//rtsc/cloud-transcoder/tasks' \ --header 'Accept: application/json' \ --header 'Authorization: ' \ --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)。