# Update a cloud transcoding task (/en/api-reference/api-ref/cloud-transcoding/update)

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

Updates an existing Cloud Transcoding task.

- OpenAPI: /openapi/cloud-transcoding/cloud-transcoding.en.yaml
- Operation ID: update-cloud-transcoding-task
- Method: PATCH
- Path: /v1/projects/{appId}/rtsc/cloud-transcoder/tasks/{taskId}

## Servers

- https://api.sd-rtn.com

## Parameters

- `Content-Type` (header, required) - The request content type. Use `application/json`.
- `X-Request-ID` (header, optional) - UUID (Universally Unique Identifier), used to identify this request.

If the request fails, print out the value in the log to troubleshoot the problem. If the response status code of the request is not 2XX, then the response header may not contain this field.
- `appId` (path, required) - The App ID of your project from Agora Console.
- `taskId` (path, required) - The transcoding task UUID used to identify the cloud transcoder for this request.
- `builderToken` (query, required) - The `tokenName` you obtained in the response body of the `Acquire` method. See Acquire a builder token.
- `sequenceId` (query, required) - The sequence number of the `Update` request. Each subsequent `Update` request must use a value greater than the previous one.
- `updateMask` (query, required) - Specifies the configuration item to be updated. Set it to `services.cloudTranscoder.config` to indicate a full update.

## Request body

- `services` (object, required)
  - `services.cloudTranscoder` (object, required)
    - `services.cloudTranscoder.serviceType` (string, required) - Should be `"cloudTranscoderV2"`.

The service type. Use "cloudTranscoderV2".
No schema.
    - `services.cloudTranscoder.config` (object, required) - Same as the fields you set in the `Create` request body.
      - `services.cloudTranscoder.config.transcoder` (object, required)
        - `services.cloudTranscoder.config.transcoder.idleTimeout` (number) - The maximum period, in seconds, that Cloud Transcoder can be idle. If the idle state exceeds this value, Cloud Transcoder is automatically destroyed.
No schema.
        - `services.cloudTranscoder.config.transcoder.streamProcessMode` (string) - If this parameter is not specified, the working mode of Cloud transcoder is the merge mode. You can specify the following modes:
- `heterogeneous-single`: Heterogeneous single stream mode. The types of input stream and output stream can be different or the same. The currently supported stream types are RTC and CDN.
- `single`: RTC stream relay mode. Relays the host's audio and video data and signaling in the source channel to the destination channel.
No schema.
        - `services.cloudTranscoder.config.transcoder.audioInputs` (array) - Audio input source list, supports two types: RTC audio stream and CDN audio stream. If you specify multiple input audio sources, the streams are mixed.
          - `services.cloudTranscoder.config.transcoder.audioInputs.items` (object)
            - `services.cloudTranscoder.config.transcoder.audioInputs.items.streamUrl` (string) - The URL of the audio source stream. Required when the audio input source is CDN.
No schema.
            - `services.cloudTranscoder.config.transcoder.audioInputs.items.volume` (number) - The volume of the audio source stream. This parameter only takes effect when the audio input source is CDN.
No schema.
            - `services.cloudTranscoder.config.transcoder.audioInputs.items.repeat` (number) - The number of times to play the media stream. `1` means play once, `-1` means loop, and any positive integer specifies a playback count.
No schema.
            - `services.cloudTranscoder.config.transcoder.audioInputs.items.rtc` (object) - When the audio input source is RTC, this object is required.
              - `services.cloudTranscoder.config.transcoder.audioInputs.items.rtc.rtcChannel` (string, required) - The RTC channel name for the transcoded audio and video.

The RTC channel name for the audio input source. Currently, you can only subscribe to audio and video sources from a single channel; the audio and video sources must belong to the same channel.

The RTC channel name for the video input source. Currently, you can only subscribe to audio and video sources from a single channel; the audio and video sources must belong to the same channel.
No schema.
              - `services.cloudTranscoder.config.transcoder.audioInputs.items.rtc.rtcUid` (number, required) - The UID of the RTC channel for the transcoded audio and video streams. Make sure this value is different from the UID of other users in the channel.

The UID corresponding to the audio input source. The same UID must not exist in the RTC channel.

The UID corresponding to the video input source. The same UID must not exist in the RTC channel.
No schema.
              - `services.cloudTranscoder.config.transcoder.audioInputs.items.rtc.rtcToken` (string, required) - The token that the Cloud Transcoder uses to join the output RTC channel. Using a token ensures channel security and prevents malicious users from disrupting other users in the channel. See Token authentication for details.

 When generating this token, use `outputs.rtc.rtcUid` to generate the token.

The token that the Cloud Transcoder uses to join the RTC channel for transcoding. Using a token ensures channel security and prevents malicious users from disrupting other users in the channel. See Token authentication for details.

 The UID of Cloud Transcoder in the RTC channel is randomly assigned by Agora. Therefore, when generating a token, set the uid to 0.
No schema.
        - `services.cloudTranscoder.config.transcoder.videoInputs` (array) - Video input source list, supports RTC video stream and CDN video stream. If you specify multiple input video sources, the streams are merged.
          - `services.cloudTranscoder.config.transcoder.videoInputs.items` (object)
            - `services.cloudTranscoder.config.transcoder.videoInputs.items.streamUrl` (string) - The URL of the video source stream. Required when the video input source is CDN.
No schema.
            - `services.cloudTranscoder.config.transcoder.videoInputs.items.repeat` (number) - The number of times to play the media stream. `1` means play once, `-1` means loop, and any positive integer specifies a playback count.
No schema.
            - `services.cloudTranscoder.config.transcoder.videoInputs.items.rtc` (object) - This object is required when the video input source is RTC.
              - `services.cloudTranscoder.config.transcoder.videoInputs.items.rtc.rtcChannel` (string, required) - The RTC channel name for the transcoded audio and video.

The RTC channel name for the audio input source. Currently, you can only subscribe to audio and video sources from a single channel; the audio and video sources must belong to the same channel.

The RTC channel name for the video input source. Currently, you can only subscribe to audio and video sources from a single channel; the audio and video sources must belong to the same channel.
No schema.
              - `services.cloudTranscoder.config.transcoder.videoInputs.items.rtc.rtcUid` (number, required) - The UID of the RTC channel for the transcoded audio and video streams. Make sure this value is different from the UID of other users in the channel.

The UID corresponding to the audio input source. The same UID must not exist in the RTC channel.

The UID corresponding to the video input source. The same UID must not exist in the RTC channel.
No schema.
              - `services.cloudTranscoder.config.transcoder.videoInputs.items.rtc.rtcToken` (string, required) - The token that the Cloud Transcoder uses to join the output RTC channel. Using a token ensures channel security and prevents malicious users from disrupting other users in the channel. See Token authentication for details.

 When generating this token, use `outputs.rtc.rtcUid` to generate the token.

The token that the Cloud Transcoder uses to join the RTC channel for transcoding. Using a token ensures channel security and prevents malicious users from disrupting other users in the channel. See Token authentication for details.

 The UID of Cloud Transcoder in the RTC channel is randomly assigned by Agora. Therefore, when generating a token, set the uid to 0.
No schema.
            - `services.cloudTranscoder.config.transcoder.videoInputs.items.placeholderImageUrl` (string) - The URL of the placeholder image displayed when the user is offline. It must be a valid image URL and contain the `jpg` or `png` suffix.
No schema.
            - `services.cloudTranscoder.config.transcoder.videoInputs.items.region` (object, required)
              - `services.cloudTranscoder.config.transcoder.videoInputs.items.region.x` (number, required) - The x coordinate of the watermark on the canvas (px). The x coordinate is the horizontal displacement of the upper left corner of the image relative to the origin.

The x coordinate of the image on the canvas (px). The x coordinate is the horizontal displacement of the upper left corner of the image relative to the origin, where the upper left corner of the canvas is the origin.
No schema.
              - `services.cloudTranscoder.config.transcoder.videoInputs.items.region.y` (number, required) - The y coordinate of the watermark on the canvas (px). The y coordinate is the vertical displacement of the upper left corner of the image relative to the origin.

The y coordinate of the image on the canvas (px). The y coordinate is the vertical displacement of the upper left corner of the image relative to the origin, where the upper left corner of the canvas is the origin.
No schema.
              - `services.cloudTranscoder.config.transcoder.videoInputs.items.region.width` (number, required) - The width of the watermark (px).

The width of the screen (px).
No schema.
              - `services.cloudTranscoder.config.transcoder.videoInputs.items.region.height` (number, required) - The height of the watermark (px).

The height of the screen (px).
No schema.
              - `services.cloudTranscoder.config.transcoder.videoInputs.items.region.zOrder` (number, required) - The layer order of the watermark. `0` represents the bottom layer. `100` represents the top layer.

The layer order of the host screen. 2 represents the layer above the placeholder layer. 100 represents the top layer.
No schema.
        - `services.cloudTranscoder.config.transcoder.canvas` (object, required)
          - `services.cloudTranscoder.config.transcoder.canvas.width` (number, required) - The width of the canvas (px).
No schema.
          - `services.cloudTranscoder.config.transcoder.canvas.height` (number, required) - The height of the canvas (px).
No schema.
          - `services.cloudTranscoder.config.transcoder.canvas.color` (number, required) - The background color of the canvas as a decimal RGB value.
No schema.
          - `services.cloudTranscoder.config.transcoder.canvas.backgroundImage` (string) - Canvas background image. Must be a valid image URL with a `jpg` or `png` suffix. If omitted, there is no canvas background image.
No schema.
          - `services.cloudTranscoder.config.transcoder.canvas.fillMode` (string) - Fill mode for the canvas background image.
No schema.
        - `services.cloudTranscoder.config.transcoder.watermarks` (array, required) - Watermark list.
          - `services.cloudTranscoder.config.transcoder.watermarks.items` (object)
            - `services.cloudTranscoder.config.transcoder.watermarks.items.imageUrl` (string, required) - The URL of the watermark image.
No schema.
            - `services.cloudTranscoder.config.transcoder.watermarks.items.region` (object, required)
              - `services.cloudTranscoder.config.transcoder.watermarks.items.region.zOrder` (number, required) - The layer order of the watermark. `0` represents the bottom layer. `100` represents the top layer.

The layer order of the host screen. 2 represents the layer above the placeholder layer. 100 represents the top layer.
No schema.
              - `services.cloudTranscoder.config.transcoder.watermarks.items.region.x` (number, required) - The x coordinate of the watermark on the canvas (px). The x coordinate is the horizontal displacement of the upper left corner of the image relative to the origin.

The x coordinate of the image on the canvas (px). The x coordinate is the horizontal displacement of the upper left corner of the image relative to the origin, where the upper left corner of the canvas is the origin.
No schema.
              - `services.cloudTranscoder.config.transcoder.watermarks.items.region.y` (number, required) - The y coordinate of the watermark on the canvas (px). The y coordinate is the vertical displacement of the upper left corner of the image relative to the origin.

The y coordinate of the image on the canvas (px). The y coordinate is the vertical displacement of the upper left corner of the image relative to the origin, where the upper left corner of the canvas is the origin.
No schema.
              - `services.cloudTranscoder.config.transcoder.watermarks.items.region.width` (number, required) - The width of the watermark (px).

The width of the screen (px).
No schema.
              - `services.cloudTranscoder.config.transcoder.watermarks.items.region.height` (number, required) - The height of the watermark (px).

The height of the screen (px).
No schema.
            - `services.cloudTranscoder.config.transcoder.watermarks.items.fillMode` (string) - Watermark fill mode:
- `"FILL"`: Scale the image and crop it in the center while maintaining the aspect ratio.
- `"FIT"`: Scale the image to fill the display while maintaining the aspect ratio.
No schema.
        - `services.cloudTranscoder.config.transcoder.outputs` (array, required) - Configure output settings to publish to an RTC channel or CDN address.

 You must specify either `streamUrl` or `rtc`.

Configure output settings to publish to a single RTC channel or CDN address.

 You must specify either streamUrl or rtc.
          - `services.cloudTranscoder.config.transcoder.outputs.items` (object)
            - `services.cloudTranscoder.config.transcoder.outputs.items.streamUrl` (string) - CDN streaming address.
No schema.
            - `services.cloudTranscoder.config.transcoder.outputs.items.rtc` (object, required) - Required for publishing to an RTC channel. Currently, you can publish to only one RTC channel.
              - `services.cloudTranscoder.config.transcoder.outputs.items.rtc.rtcChannel` (string, required) - The RTC channel name for the transcoded audio and video.

The RTC channel name for the audio input source. Currently, you can only subscribe to audio and video sources from a single channel; the audio and video sources must belong to the same channel.

The RTC channel name for the video input source. Currently, you can only subscribe to audio and video sources from a single channel; the audio and video sources must belong to the same channel.
No schema.
              - `services.cloudTranscoder.config.transcoder.outputs.items.rtc.rtcUid` (number, required) - The UID of the RTC channel for the transcoded audio and video streams. Make sure this value is different from the UID of other users in the channel.

The UID corresponding to the audio input source. The same UID must not exist in the RTC channel.

The UID corresponding to the video input source. The same UID must not exist in the RTC channel.
No schema.
              - `services.cloudTranscoder.config.transcoder.outputs.items.rtc.rtcToken` (string, required) - The token that the Cloud Transcoder uses to join the output RTC channel. Using a token ensures channel security and prevents malicious users from disrupting other users in the channel. See Token authentication for details.

 When generating this token, use `outputs.rtc.rtcUid` to generate the token.

The token that the Cloud Transcoder uses to join the RTC channel for transcoding. Using a token ensures channel security and prevents malicious users from disrupting other users in the channel. See Token authentication for details.

 The UID of Cloud Transcoder in the RTC channel is randomly assigned by Agora. Therefore, when generating a token, set the uid to 0.
No schema.
            - `services.cloudTranscoder.config.transcoder.outputs.items.audioOption` (object)
              - `services.cloudTranscoder.config.transcoder.outputs.items.audioOption.profileType` (string) - Audio properties of the transcoded output:
- `"AUDIO_PROFILE_DEFAULT"`: 48 kHz sampling rate, music encoding, mono channel, maximum encoding bitrate is 64 Kbps.
- `"AUDIO_PROFILE_SPEECH_STANDARD"`: 32 kHz sampling rate, speech encoding, mono channel, maximum encoding bitrate is 18 Kbps.
- `"AUDIO_PROFILE_MUSIC_STANDARD"`: 48 KHz sampling rate, music encoding, mono channel, maximum encoding bitrate is 64 Kbps.
- `"AUDIO_PROFILE_MUSIC_STANDARD_STEREO"`: 48 KHz sampling rate, music encoding, stereo channel, maximum encoding bitrate is 80 Kbps.
- `"AUDIO_PROFILE_MUSIC_HIGH_QUALITY"`: 48 KHz sampling rate, music encoding, mono channel, maximum encoding bitrate is 96 Kbps.
- `"AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO"`: 48 kHz sampling rate, music encoding, dual channels, and a maximum encoding bitrate of 128 Kbps.
No schema.
            - `services.cloudTranscoder.config.transcoder.outputs.items.videoOption` (object)
              - `services.cloudTranscoder.config.transcoder.outputs.items.videoOption.width` (number, required) - The width of the transcoded output video (px).
No schema.
              - `services.cloudTranscoder.config.transcoder.outputs.items.videoOption.height` (number, required) - The height of the transcoded output video (px).
No schema.
              - `services.cloudTranscoder.config.transcoder.outputs.items.videoOption.bitrate` (number, required) - The bitrate of the transcoded output video.
No schema.
              - `services.cloudTranscoder.config.transcoder.outputs.items.videoOption.codec` (string, required) - The codec used to transcode the output video.

 **Possible values**:
- `"H264"`: Standard H.264 encoding.
- `"VP8"`: Standard VP8 encoding.
No schema.
              - `services.cloudTranscoder.config.transcoder.outputs.items.videoOption.fps` (number) - The frame rate (fps) of the transcoded output video.
No schema.
              - `services.cloudTranscoder.config.transcoder.outputs.items.videoOption.mode` (string) - Can be set to `RAW`, which means the output video is not transcoded. The encoding format of the input video remains unchanged.

 If the output video is transcoded, do not set this field.
 In `RAW` mode, the number of inputs set in `videoInputs` can only be 1.
No schema.
              - `services.cloudTranscoder.config.transcoder.outputs.items.videoOption.lowBitrateHighQuality` (boolean) - Whether to enable low-bitrate high-quality mode.
No schema.

## Responses

### 200

The request succeeded and the response body is empty.

No schema.
### default

The request failed.

- `message` (string) - Describes why the request failed.
No schema.