# 更新指定的云端转码 (/zh-CN/api-reference/api-ref/cloud-transcoding/update) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 更新指定云端转码任务的配置。 - OpenAPI: /openapi/cloud-transcoding/cloud-transcoding.zh-CN.yaml - Operation ID: patch-v1-projects-appId-rtsc-cloud-transcoder-tasks-taskId - Method: PATCH - Path: /v1/projects/{appId}/rtsc/cloud-transcoder/tasks/{taskId} - Endpoint: https://api.sd-rtn.com/v1/projects/{appId}/rtsc/cloud-transcoder/tasks/{taskId} ## Servers - https://api.sd-rtn.com `Update` 方法用于更新云端转码任务。通过 [`Acquire`](acquire) 和 [`Create`](create) 请求获取并创建 Cloud transcoder 后，你可以调用该接口更新 Cloud transcoder。 ### 可更新字段 `Update` 请求支持修改如下字段： - 新增或删除 `audioInputs[]`、`videoInputs[]` 中的 `rtc` 成员，用于订阅或取消订阅频道内主播的音视频流。 - 修改 `videoInputs[]` 中的 `region` 字段，用于更新主播的合图布局。 - 修改 `outputs[]` 中的 `audioOption`、`videoOption` 字段，用于更新转码输出的音频和视频配置。 :::info[注意] - 使用 `Update` 更新 Cloud transcoder 时，你的请求包体中需含有 [`Create`](create) 请求包体中的所有字段，对于不需要更新的字段，请维持原来的取值。 - `Create` 请求创建 Cloud transcoder 时，支持音视频、纯音频、全频道混音三种场景。调用 `Update` 更新 Cloud transcoder 时，请保持使用场景一致，否则会发生异常。 ::: ## Authorization This endpoint requires authentication. - `Basic Auth` ## Parameters - `Content-Type` (header, required, string) - `application/json` - `builderToken` (query, required, string) - 通过 `Acquire` 方法的响应包体得到的 `tokenName` 的值。 > [!CAUTION] > 请确保填入的 `builderToken` 和你在 `Create` 接口中传入的 `builderToken` 一致。 - `sequenceId` (query, required, string) - `Update` 请求的序列号。取值需要大于 0。请确保后一次 `Update` 请求的序列号大于前一次 `Update` 请求的序列号。序列号可以确保声网服务器按照你指定的最新配置来更新 Cloud transcoder。 **使用建议**：声网推荐你在第一次调用 `Update` 时，将 `sequence` 设置为 `1`。在第二次调用 `Update` 时，将 `sequence` 设置为 `2`。在第三次调用 `Update` 时，将 `sequence` 设置为 `3`。依次类推。声网服务器会按照最新 `Update` 请求（即最大的序列号）更新 Cloud transcoder。 - `updateMask` (query, required, string) - 指定的更新配置项。需要填为 `services.cloudTranscoder.config`，代表全量更新。 - `taskId` (path, required, string) - 转码任务 ID，为 UUID，用于标识本次请求操作的 Cloud transcoder。 - `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) - 预留字段。 ### Request body example ```json { "services": { "cloudTranscoder": { "serviceType": "cloudTranscoderV2", "config": { "transcoder": { "idleTimeout": 300, "audioInputs": [ { "rtc": { "rtcChannel": "test", "rtcUid": 123, "rtcToken": "aab8b8f5a8cd4469a63042fcfafe7***" } }, { "rtc": { "rtcChannel": "test01", "rtcUid": 456, "rtcToken": "aab8b8f5a8cd4469a63042fcfafe7***" } } ], "canvas": { "width": 960, "height": 480, "color": 0, "backgroundImage": "https://example.jpg", "fillMode": "FIT" }, "waterMarks": [ { "imageUrl": "https://example.png", "region": { "x": 0, "y": 0, "width": 120, "height": 120, "zOrder": 50 } } ], "videoInputs": [ { "rtc": { "rtcChannel": "test01", "rtcUid": 123, "rtcToken": "aab8b8f5a8cd4469a63042fcfafe7***" }, "placeholderImageUrl": "https://example.jpg", "region": { "x": 0, "y": 0, "width": 320, "height": 360, "zOrder": 2 } }, { "rtc": { "rtcChannel": "test01", "rtcUid": 456, "rtcToken": "aab8b8f5a8cd4469a63042fcfafe7***" }, "placeholderImageUrl": "https://example.jpg", "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，则请求成功。包体为空。 No schema. ### 非 2XX 如果状态码不为 2XX，请求失败。请根据响应状态码和 `message` 字段进行排查。 - `message` (string) - 描述请求失败的原因。 ## Response examples ### 非 2XX ```json { "message": "描述请求失败的原因。" } ```