# 获取云端转码资源 (/zh-CN/api-reference/api-ref/cloud-transcoding/acquire) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 获取用于创建云端转码任务的 builderToken。 - OpenAPI: /openapi/cloud-transcoding/cloud-transcoding.zh-CN.yaml - Operation ID: post-v1-projects-appId-rtsc-cloud-transcoder-builderTokens - Method: POST - Path: /v1/projects/{appId}/rtsc/cloud-transcoder/builderTokens - Endpoint: https://api.sd-rtn.com/v1/projects/{appId}/rtsc/cloud-transcoder/builderTokens ## Servers - https://api.sd-rtn.com `Acquire` 方法用于在开始云端转码前获取云端转码资源。 :::info[注意] - 调用成功后,你可以在响应包体中得到一个 `builderToken`。一个 `builderToken` 仅可用于一次云端转码任务,同一时间仅允许一个 `builderToken` 运行任务。 - `builderToken` 用于创建云端转码的有效期为 5 分钟。为确保成功进行云端转码,建议你在每次 `Acquire` 请求获取到 `builderToken` 后的 2 秒内立即发起对应的 [`Create`](create) 请求。 - 成功创建后,如果需要调用 `Update`/`Delete`,请求中传入的 `builderToken` 需要和创建云端转码时传入的 `builderToken` 一致。 - 在批量获取 `builderToken` 后进行批量 `Create` 请求可能导致请求失败。 ::: ## Authorization This endpoint requires authentication. - `Basic Auth` ## Parameters - `Content-Type` (header, required, string) - `application/json` - `appId` (path, required, string) - 声网为每个开发者提供的 **App ID**。在声网控制台创建一个项目后即可得到一个 App ID。一个 App ID 是一个项目的唯一标识。 ## Request body - `services` (object, required) - `services.cloudTranscoder` (object, required) - `services.cloudTranscoder.serviceType` (string, required) - 服务类型,此处为 `"cloudTranscoderV2"`。 - `services.cloudTranscoder.config` (object, required) - `services.cloudTranscoder.config.transcoder` (object, required) - Cloud transcoder 服务配置项。 - `services.cloudTranscoder.config.transcoder.idleTimeout` (number) - 空闲超时时间(秒)。空闲指 Cloud transcoder 处理的音视频流所对应的所有主播均已离开频道。当没有输入超过设置的时间(秒)后,Cloud transcoder 会停止工作并自动销毁,以节省资源。 - Default: `300` - Range: `[1, 86400]` - `services.cloudTranscoder.config.transcoder.streamProcessMode` (string) - Cloud transcoder 的工作模式,如果不指定此参数,就是合图模式。可以指定类型如下: - `"heterogeneous-single"`: 异构单流模式,也就是输入流和输出流的类型可以不同,也可以相同,当前支持的流类型是 RTC 流和 CDN 流。 - `"single"`: RTC 流 Relay 模式,即把源频道内主播的音视频数据和信令一同 Relay 到目的频道。 > [!CAUTION] > - 如果 `streamProcessMode` 设置为 `"heterogeneous-single"` 或者 `"single"`,那 `audioInputs` 或者 `videoInputs` 列表最多只能包含一项。 > - 如果需要混音、合图或混音合图,则无需设置 `streamProcessMode`。 - Default: `mix` - `services.cloudTranscoder.config.transcoder.audioInputs` (array) - 音频输入源列表,支持 RTC 音频流和 CDN 音频流两种类型。如果 `audioInputs` 包含多个输入音频源,则表示需要混音。 > [!CAUTION] > `streamUrl` 和 `rtc` 两者中必须填一个。 - `services.cloudTranscoder.config.transcoder.audioInputs.items` (object) - `services.cloudTranscoder.config.transcoder.audioInputs.items.streamUrl` (string) - 音频源流的 URL。 > [!CAUTION] > 在音频输入源是 CDN 场景下,该参数为必填。 - `services.cloudTranscoder.config.transcoder.audioInputs.items.volume` (number) - 音频源流的音量。 > [!NOTE] > 仅在音频输入源是 CDN 场景下设置。 - Default: `100` - Range: `[0, 200]` - `services.cloudTranscoder.config.transcoder.audioInputs.items.repeat` (object) - 媒体流播放重复次数: - `1`:(默认)播放媒体流一次。 - `-1`:循环播放媒体流。 - `n`:自定义播放媒体流次数。不可设置为 0。 > [!NOTE] > 仅在音频输入源是 CDN 场景下设置。 - `services.cloudTranscoder.config.transcoder.audioInputs.items.rtc` (object) - 在音频输入源是 RTC 场景下,该对象为必填。 - `services.cloudTranscoder.config.transcoder.audioInputs.items.rtc.rtcChannel` (string, required) - 频道名称,用于指定来源音频流来自那个频道。目前仅支持订阅单个频道的音视频源,音频源和视频源所属频道必须相同。 - `services.cloudTranscoder.config.transcoder.audioInputs.items.rtc.rtcUid` (number, required) - 音频输入源所对应的 UID。在 RTC 系统中每个主播在频道内身份的唯一标识。 - `services.cloudTranscoder.config.transcoder.audioInputs.items.rtc.rtcToken` (string, required) - Cloud transcoder 在进入待转码视频源所属 RTC 频道时所需设置的 Token。该值可用于确保频道安全,避免异常用户扰乱频道内其他用户。详见[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。 > [!CAUTION] > Cloud transcoder 在待转码音视频源所属 RTC 频道内的 UID 为声网随机分配,因此,生成 Token 时,你使用的 `uid` 必须为 0。 - `services.cloudTranscoder.config.transcoder.videoInputs` (array) - 视频输入源列表,支持 RTC 视频流和 CDN 视频流两种类型。如果 `videoInputs` 包含多个输入视频源,则表示需要合图。 > [!CAUTION] > `streamUrl` 和 `rtc` 两者中必须填一个。 - `services.cloudTranscoder.config.transcoder.videoInputs.items` (object) - `services.cloudTranscoder.config.transcoder.videoInputs.items.streamUrl` (string) - 视频源流的 URL。 > [!CAUTION] > 在视频输入源是 CDN 场景下,该参数为必填。 - `services.cloudTranscoder.config.transcoder.videoInputs.items.repeat` (object) - 媒体流播放重复次数: - `1`:(默认)播放媒体流一次。 - `-1`:循环播放媒体流。 - `n`:自定义播放媒体流次数。不可设置为 0。 > [!NOTE] > 仅在音频输入源是 CDN 场景下设置。 - `services.cloudTranscoder.config.transcoder.videoInputs.items.rtc` (object) - 在视频输入源是 RTC 场景下,该对象为必填。 - `services.cloudTranscoder.config.transcoder.videoInputs.items.rtc.rtcChannel` (string, required) - 频道名称,用于指定来源视频流来自哪个频道。 - `services.cloudTranscoder.config.transcoder.videoInputs.items.rtc.rtcUid` (number, required) - 视频输入源所对应的 UID。在 RTC 系统中每个主播在频道内身份的唯一标识。 - `services.cloudTranscoder.config.transcoder.videoInputs.items.rtc.rtcToken` (string, required) - Cloud transcoder 在进入待转码视频源所属 RTC 频道时所需设置的 Token。该值可用于确保频道安全,避免异常用户扰乱频道内其他用户。详见[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。 > [!CAUTION] > Cloud transcoder 在待转码音视频源所属 RTC 频道内的 UID 为声网随机分配,因此,生成 Token 时,你使用的 `uid` 必须为 0。 - `services.cloudTranscoder.config.transcoder.videoInputs.items.placeholderImageUrl` (string) - 用户离线时占位图片的 URL。必须为合法 URL,且包含 `jpg` 或 `png` 后缀。 - `services.cloudTranscoder.config.transcoder.videoInputs.items.region` (object, required) - 视频流画面在其画布上布局的位置和大小信息。 > [!CAUTION] > 如果需要合图,那 `videoInputs` 列表中的每一项都要设置 `region` 字段,指定其在输出画布中的位置,要保证不能超过画布大小。 - `services.cloudTranscoder.config.transcoder.videoInputs.items.region.x` (number, required) - 画面在画布上的 x 坐标 (px)。以画布左上角为原点,x 坐标为画面左上角相对于原点的横向位移。 - Range: `[0, 3840]` - `services.cloudTranscoder.config.transcoder.videoInputs.items.region.y` (number, required) - 画面在画布上的 y 坐标 (px)。以画布左上角为原点,y 坐标为画面左上角相对于原点的纵向位移。 - Range: `[0, 3840]` - `services.cloudTranscoder.config.transcoder.videoInputs.items.region.width` (number, required) - 画面的宽度 (px)。 - Range: `[120, 3840]` - `services.cloudTranscoder.config.transcoder.videoInputs.items.region.height` (number, required) - 画面的高度 (px)。 - Range: `[120, 3840]` - `services.cloudTranscoder.config.transcoder.videoInputs.items.region.zOrder` (number, required) - 主播画面的图层编号。2 代表占位图图层所在的上面一层。100 代表最上层的图层。 - Range: `[2, 100]` - `services.cloudTranscoder.config.transcoder.canvas` (object) - 输出画布。 - `services.cloudTranscoder.config.transcoder.canvas.width` (number, required) - 画布的宽度 (px)。 - Range: `[120, 3840]` - `services.cloudTranscoder.config.transcoder.canvas.height` (number, required) - 画布的高度 (px)。取值范围为 [120,3840]。 - Range: `[120, 3840]` - `services.cloudTranscoder.config.transcoder.canvas.color` (number, required) - 画布的背景色。RGB 颜色值,以十进制数表示。如 0 代表黑色,255 代表蓝色。 - Range: `[0, 16777215]` - `services.cloudTranscoder.config.transcoder.canvas.backgroundImage` (string) - 画布背景图。必须为合法 URL,且包含 `jpg` 或 `png` 后缀。 > [!NOTE] > 如果不传值,则没有画布背景图。 - `services.cloudTranscoder.config.transcoder.canvas.fillMode` (string) - 画布背景图的填充模式: - `"FILL"`:在保持长宽比的前提下,缩放画面,并居中剪裁。详见[示意图](https://web-cdn.agora.io/docs-files/1628837665989) 。 - `"FIT"`:在保持长宽比的前提下,缩放画面,使其完整显示。详见[示意图](https://web-cdn.agora.io/docs-files/1628837708782) 。 - Default: `FILL` - `services.cloudTranscoder.config.transcoder.watermarks` (array) - `services.cloudTranscoder.config.transcoder.watermarks.items` (object) - `services.cloudTranscoder.config.transcoder.watermarks.items.imageUrl` (string, required) - 水印图片的 URL。必须为合法 URL,且包含 `jpg` 或 `png` 后缀。 - `services.cloudTranscoder.config.transcoder.watermarks.items.region` (object, required) - `services.cloudTranscoder.config.transcoder.watermarks.items.region.x` (number, required) - 水印在画布上的 x 坐标 (px)。以画布左上角为原点,x 坐标为画面左上角相对于原点的横向位移。 - Range: `[0, 3840]` - `services.cloudTranscoder.config.transcoder.watermarks.items.region.y` (number, required) - 水印在画布上的 y 坐标 (px)。以画布左上角为原点,y 坐标为画面左上角相对于原点的纵向位移。 - Range: `[0, 3840]` - `services.cloudTranscoder.config.transcoder.watermarks.items.region.width` (number, required) - 水印的宽度 (px)。 - Range: `[120, 3840]` - `services.cloudTranscoder.config.transcoder.watermarks.items.region.height` (number, required) - 水印的高度 (px)。 - Range: `[120, 3840]` - `services.cloudTranscoder.config.transcoder.watermarks.items.region.zOrder` (number, required) - 水印的图层编号。0 代表最下层的图层。100 代表最上层的图层。 - Range: `[0, 100]` - `services.cloudTranscoder.config.transcoder.watermarks.items.fillMode` (string) - 水印的填充模式: - `"FILL"`:在保持长宽比的前提下,缩放画面,并居中剪裁。详见[示意图](https://web-cdn.agora.io/docs-files/1628837665989) 。 - `"FIT"`:在保持长宽比的前提下,缩放画面,使其完整显示。详见[示意图](https://web-cdn.agora.io/docs-files/1628837708782) 。 - Default: `FILL` - `services.cloudTranscoder.config.transcoder.outputs` (array, required) - 服务配置的输出设置,可选择输出到 RTC 频道或者 CDN 地址。 > [!CAUTION] > `streamUrl` 和 `rtc` 两者中必须填一个。 - `services.cloudTranscoder.config.transcoder.outputs.items` (object) - `services.cloudTranscoder.config.transcoder.outputs.items.streamUrl` (string) - CDN 推流地址。 > [!CAUTION] > 在输出到 CDN 推流地址场景中,该参数为必填。 - `services.cloudTranscoder.config.transcoder.outputs.items.rtc` (object) - 在输出到 RTC 场景中,该对象为必填。 - `services.cloudTranscoder.config.transcoder.outputs.items.rtc.rtcToken` (string, required) - Cloud transcoder 在进入输出音视频流所属 RTC 频道时所需设置的 Token。该值可用于确保频道安全,避免异常用户扰乱频道内其他用户。详见[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。 > [!CAUTION] > Cloud transcoder 在转码输出音视频流所属 RTC 频道内的 UID 为你指定的 `outputs.rtc.rtcUid`,因此,生成 Token 时,你使用的 `uid` 必须和 `outputs.rtc.rtcUid` 一致。 - `services.cloudTranscoder.config.transcoder.outputs.items.rtc.rtcChannel` (string, required) - 转码输出的音视频流所属的 RTC 频道名。 - `services.cloudTranscoder.config.transcoder.outputs.items.rtc.rtcUid` (number, required) - Cloud transcoder 在转码输出音视频流所属 RTC 频道内的 UID。RTC 频道内不允许存在相同的 UID,因此,请确保该值与频道内其他用户 UID 不同。 - `services.cloudTranscoder.config.transcoder.outputs.items.audioOption` (object) - 输出音频编码参数。默认值: `AUDIO_PROFILE_DEFAULT`。 - `services.cloudTranscoder.config.transcoder.outputs.items.audioOption.profileType` (string) - 转码输出的音频属性: - `"AUDIO_PROFILE_DEFAULT"`:48 kHz 采样率,音乐编码,单声道,编码码率最大值为 64 Kbps。 - `"AUDIO_PROFILE_SPEECH_STANDARD"`:32 kHz 采样率,语音编码,单声道,编码码率最大值为 18 Kbps。 - `"AUDIO_PROFILE_MUSIC_STANDARD"`: 48 KHz 采样率,音乐编码,单声道,编码码率最大值为 64 Kbps。 - `"AUDIO_PROFILE_MUSIC_STANDARD_STEREO"`:48 KHz 采样率,音乐编码,双声道,编码码率最大值为 80 Kbps。 - `"AUDIO_PROFILE_MUSIC_HIGH_QUALITY"`:48 KHz 采样率,音乐编码,单声道,编码码率最大值为 96 Kbps。 - `"AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO"`:48 KHz 采样率,音乐编码,双声道,编码码率最大值为 128 Kbps。 - `services.cloudTranscoder.config.transcoder.outputs.items.videoOption` (object) - 输出视频的编码参数。 > [!CAUTION] > 支持的最大转码分辨率为 1080p (1920 x 1080 px)。 - `services.cloudTranscoder.config.transcoder.outputs.items.videoOption.width` (number, required) - 转码输出视频的宽度 (px)。 - Range: `[120, 3840]` - `services.cloudTranscoder.config.transcoder.outputs.items.videoOption.height` (number, required) - 转码输出视频的高度 (px)。 - Range: `[120, 3840]` - `services.cloudTranscoder.config.transcoder.outputs.items.videoOption.bitrate` (number, required) - 转码输出视频的码率。 - Range: `[1, 10000]` - `services.cloudTranscoder.config.transcoder.outputs.items.videoOption.codec` (string, required) - 转码输出视频的 codec。取值包括: - `"H264"`:标准 H.264 编码。 - `"VP8"`:标准 VP8 编码。 - `services.cloudTranscoder.config.transcoder.outputs.items.videoOption.fps` (number) - 转码输出视频的帧率 (fps)。 - Default: `15` - Range: `[1, 30]` - `services.cloudTranscoder.config.transcoder.outputs.items.videoOption.mode` (string) - 可以设为 `"RAW"`,表示输出视频不转码,即保持输入视频的编码格式不变。 > [!CAUTION] > - 如果输出的视频转码,请勿设置该字段。 > - `"RAW"` 模式下,`videoInputs` 中设置的输入数量只能为 1。 - `services.cloudTranscoder.config.transcoder.outputs.items.seiOption` (object) - 预留字段。 - `services.cloudTranscoder.config.transcoder.outputs.items.seiOption.source` (object) - 预留字段。 - `services.cloudTranscoder.config.transcoder.outputs.items.seiOption.source.agora` (object) - 预留字段。 - `services.cloudTranscoder.config.transcoder.outputs.items.seiOption.source.agora.uidVideoLayout` (boolean) - 预留字段。 - `services.cloudTranscoder.config.transcoder.outputs.items.seiOption.sink` (object) - 预留字段。 - `services.cloudTranscoder.config.transcoder.outputs.items.seiOption.sink.type` (integer) - 预留字段。 - `instanceId` (string, required) - 用户指定的实例 ID。长度必须在 64 个字符以内,支持的字符集范围为: - 所有小写英文字母(a-z) - 所有大写英文字母(A-Z) - 数字 0-9 - "-", "_" > [!CAUTION] > 一个 `instanceId` 可以生成多个 `builderToken`,但同一时间仅允许一个 `builderToken` 运行任务。 ### Request body example ```json { "instanceId": "abc13328", "services": { "cloudTranscoder": { "serviceType": "cloudTranscoderV2", "config": { "transcoder": { "idleTimeout": 300, "audioInputs": [ { "rtc": { "rtcChannel": "test01", "rtcUid": 123, "rtcToken": "aab8b8f5a8cd4469a63042fcfafe7***" } }, { "rtc": { "rtcChannel": "test01", "rtcUid": 456, "rtcToken": "aab8b8f5a8cd4469a63042fcfafe7***" } } ], "canvas": { "width": 960, "height": 480, "color": 0, "backgroundImage": "https://web-cdn.agora.io/website-files/images/new-home-2-banne-online-karaoke-bg.jpg", "fillMode": "FIT" }, "waterMarks": [ { "imageUrl": "https://web-cdn.agora.io/website-files/images/advantage-interactive-live-streaming.png", "region": { "x": 0, "y": 0, "width": 100, "height": 100, "zOrder": 50 } } ], "videoInputs": [ { "rtc": { "rtcChannel": "test01", "rtcUid": 123, "rtcToken": "aab8b8f5a8cd4469a63042fcfafe7***" }, "placeholderImageUrl": "https://web-cdn.agora.io/website-files/images/new-home-2-banner-realtime-bg.jpg", "region": { "x": 0, "y": 0, "width": 320, "height": 360, "zOrder": 2 } }, { "rtc": { "rtcChannel": "test01", "rtcUid": 456, "rtcToken": "aab8b8f5a8cd4469a63042fcfafe7***" }, "region": { "x": 320, "y": 0, "width": 320, "height": 320, "zOrder": 2 } } ], "outputs": [ { "rtc": { "rtcChannel": "test02", "rtcUid": 1000, "rtcToken": "aab8b8f5a8cd4469a63042fcfafe7***" }, "audioOption": { "profileType": "AUDIO_PROFILE_MUSIC_STANDARD" }, "videoOption": { "fps": 30, "codec": "H264", "bitrate": 800, "width": 960, "height": 480, "lowBitrateHighQuality": false } } ] } } } } } ``` ## Responses ### 2XX 如果状态码为 2XX,则请求成功。 - `createTs` (number) - 生成 `builderToken` 时的 Unix 时间戳(秒)。 - `instanceId` (string) - 请求时设置的 `instanceId`。 - `tokenName` (string) - 代表 `builderToken` 的值,在后续调用其他方法时需要传入该值。 ### 非 2XX 如果状态码不为 2XX,请求失败。请根据响应状态码和 `message` 字段进行排查。 - `message` (string) - 描述请求失败的原因。 ## Response examples ### 2XX ```json { "createTs": 1661324606, "instanceId": "abc13328", "tokenName": "nUwUbQf9Zg6tsgtLslGnDg0lk8RYaUE0***" } ``` ### 非 2XX ```json { "message": "描述请求失败的原因。" } ```