All Products
Search

This Product

    ApsaraVideo VOD:Image and text watermarks

    Document Center

    ApsaraVideo VOD:Image and text watermarks

    Last Updated:Jan 28, 2026

    Video watermarking adds identifying information to a video, such as a company logo, TV station icon, user nickname, or user ID. Watermarking helps highlight your brand, protect your copyright, and increase product recognition. ApsaraVideo VOD supports three types of watermarks: static images, animated images, and text. You can choose the type that best suits your needs.

    How it works

    Watermarking in ApsaraVideo VOD is based on transcoding. During the transcoding process, information such as images and text is embedded into the video stream. This process creates a new video file that contains the watermark.

    Scenarios

    • Short videos

      In short video applications, downloaded and shared videos usually have an image watermark, such as a product logo, and a text watermark, such as a user ID, to protect copyright.

    • Audio and video websites

      Audio and video websites often add brand logos to videos to indicate copyright ownership. In variety shows, stickers are also added to increase engagement or display advertisements.

    Watermark types

    Type

    Supported formats

    Instructions

    Image

    • Static image: PNG

    • Animated image: GIF, APNG, MOV

    • Create watermark templates for PNG and GIF files in the console. Create watermark templates for PNG, GIF, APNG, and MOV files by calling the OpenAPI.

    • Animated watermarks are restricted by file name extension. The extensions gif, apng, and mov must be in lowercase. Static images are not restricted by file name extension.

    • The watermark image must be stored in the same bucket as the video that you want to watermark. For example, if a video is stored in an ApsaraVideo VOD bucket in the China (Shanghai) region, the watermark file must also be stored in an ApsaraVideo VOD bucket in the China (Shanghai) region. Cross-region and cross-bucket storage are not supported. For more information about storage buckets, see Storage management.

    • Set the display duration for an image watermark. This lets you display the watermark from the beginning to the end of the video, or only for a specific period.

    Text

    -

    Set the font, font size, color, opacity, and outline effects for the text.

    Billing

    Watermarking is based on transcoding, and the transcoding process incurs fees. For more information about billing, see Media transcoding billing.

    How to use

    Step 1: Create a watermark template

    To simplify watermarking, ApsaraVideo VOD uses templates to store complex watermark parameters. These parameters include the position, size, font, and color of a watermark. Each template has a unique ID.

    Using the console

    1. Log on to the ApsaraVideo VOD console.

    2. In the left-side navigation pane, choose Configuration Management > Media Processing > Watermarks.

    3. Click Create Watermark. Set the parameters for an image or text watermark.

      Image watermark parameters

      Parameter

      Description

      Watermark Type

      Select Image.

      Watermark Material

      Upload the watermark image.

      Note

      The console supports only PNG and GIF files that are no larger than 20 MB.

      Watermark Name

      Enter a name for the watermark template.

      Note

      The name can contain Chinese characters, English letters, digits, number signs (#), and hyphens (-).

      Size (Width × Height)

      Set the size of the watermark image. For more information, see Details about watermark position and size parameters.

      • Positive integer: The unit is pixel. The value must be an integer from 8 to 4096.

      • Percentage of video: The unit is %. The value can be a number from 0 to 100, accurate to two decimal places.

      Note

      If you set only the width or height of the watermark image, the other dimension is scaled based on the aspect ratio of the source image.

      Position

      The approximate position of the watermark image relative to the output video. The default value is TopRight. This parameter specifies the initial position of the watermark. For more information, see Details about watermark position and size parameters. Valid values:

      • TopLeft

      • BottomLeft

      • TopRight

      • BottomRight

      Horizontal offset

      The horizontal offset of the watermark image in the output video. For more information, see Details about watermark position and size parameters.

      • Positive integer: The unit is pixel. The value must be an integer from 8 to 4096.

      • Percentage of video: The unit is %. The value can be a number from 0 to 100, accurate to two decimal places.

      Vertical offset

      The vertical offset of the watermark image in the output video. For more information, see Details about watermark position and size parameters.

      • Positive integer: The unit is pixel. The value must be an integer from 8 to 4096.

      • Percentage of video: The unit is %. The value can be a number from 0 to 100, accurate to two decimal places.

      Timeline

      The watermark timeline controls the start time and duration of the image watermark in the video. You can configure multiple watermarks to create dynamic display effects.

      Note

      This parameter is not supported for text watermarks.

      Preview video size (Width × Height)

      Enter the dimensions of your actual video to preview the position and effect of the watermark. The unit is pixel.

      Text watermark parameters

      Parameter

      Description

      Watermark Type

      Select Text.

      Watermark Content

      Enter the text to be used as the watermark.

      Watermark Name

      Enter a name for the watermark template.

      Note

      The name can contain Chinese characters, English letters, digits, number signs (#), and hyphens (-).

      Font

      The font of the watermark text. Valid values:

      • Simsun

      • WenQuanYi Zen Hei

      • WenQuanYi Zen Hei Mono

      • WenQuanYi Zen Hei Sharp

      • Simplified Chinese Rounded Regular

      Font size

      The font size of the watermark text. The unit is pixel.

      Transparency

      The opacity of the watermark text. A smaller value indicates higher transparency. The value must be a number from 0 to 1, exclusive of 0, accurate to two decimal places.

      Font color

      Set the font color of the watermark text.

      Outline width

      The width of the font outline. The unit is pixel. The value must be a number from 0 to 4096, exclusive of 0.

      Outline color

      Set the color of the font outline.

      Vertical offset

      The vertical offset of the watermark text in the output video. For more information, see Details about watermark position and size parameters.

      Positive integer: The unit is pixel. The value must be an integer from 8 to 4096.

      Horizontal offset

      The horizontal offset of the watermark text in the output video. For more information, see Details about watermark position and size parameters.

      Positive integer: The unit is pixel. The value must be an integer from 8 to 4096.

      Preview video size

      Enter the dimensions of your actual video to preview the position and effect of the watermark text. The unit is pixel.

    4. Click Save to complete the configuration.

      After the watermark template is created, you can view the template and its ID on the Watermark Templates page.

    Using the OpenAPI

    Call the AddWatermarkTemplate operation to create a watermark template. After the template is created, the operation returns a template ID.

    Note

    When you use an API operation to create an image watermark template, you must first call the GetAuxiliaryUploadAddressAndAuth operation to upload the watermark image to ApsaraVideo VOD. For more information about how to upload a file, see Upload media files using ApsaraVideo VOD APIs.

    Details about watermark position and size parameters

    • Image watermarks

      Use the ReferPos, Dx, Dy, Width, and Height parameters to control the display position and size of the image in the output video.

      API parameter

      Console parameter

      Description

      ReferPos

      Position

      The approximate position of the watermark relative to the output video.

      • Upper-left corner: TopLeft

      • Lower-left corner: BottomLeft

      • Upper-right corner: TopRight

      • Lower-right corner: BottomRight

      Dx

      Horizontal offset

      The horizontal offset of the watermark in the output video. Valid values:

      • Positive integer. The unit is pixel. The value must be an integer from 8 to 4096.

      • Percentage of video. The unit is %. The value must be a number from 0 to 1, exclusive of 0.

      Dy

      Vertical offset

      The vertical offset of the watermark in the output video. Valid values:

      • Positive integer. The unit is pixel. The value must be an integer from 8 to 4096.

      • Percentage of video. The unit is %. The value must be a number from 0 to 1, exclusive of 0.

      Width

      Size (Width)

      The width of the watermark in the output video. Valid values:

      • Positive integer. The unit is pixel. The value must be an integer from 8 to 4096.

      • Percentage of video. The unit is %. The value must be a number from 0 to 1, exclusive of 0.

      Height

      Size (Height)

      The height of the watermark in the output video. Valid values:

      • Positive integer. The unit is pixel. The value must be an integer from 8 to 4096.

      • Percentage of video. The unit is %. The value must be a number from 0 to 1, exclusive of 0.

      Timeline

      Timeline

      The timeline of a watermark. This parameter specifies the start time and duration of the image watermark in the video. You can configure multiple watermarks to create dynamic display effects for the image watermark. For more information, see Watermark timeline.

      Important

      This parameter is not supported for text watermarks.

      Diagram

      To center the watermark, set the Dx and Dy parameters to 0.5. This sets the offset of the watermark to 50% of the width and height of the output video.图片水印位置

    • Text watermarks

      Text watermarks can be offset only from the upper-left corner of the output video. The Top and Left parameters are used for the offset. Only pixel values are supported. Percentage values are not supported.

      API parameter

      Console parameter

      Description

      Top

      Vertical offset

      The distance between the text watermark and the top of the output video. The unit is pixel. The value must be an integer from 8 to 4096.

      Left

      Horizontal offset

      The distance between the text watermark and the left side of the output video. The unit is pixel. The value must be an integer from 8 to 4096.

      Diagram文字水印

    • Calculation methods

      The Dx, Dy, Width, and Height parameters for image watermarks support pixel and percentage values. The Top and Left parameters for text watermarks support only pixel values. The details are as follows:

      • Pixel value: An integer from 8 to 4096. The unit is pixels.

        Important

        If the specified value exceeds the size of the output video, the watermark may be partially displayed or not displayed at all.

        For example, if the output video is 640 × 360 pixels, the reference position is TopLeft, and you set Dx and Dy to 4000, the watermark is not visible in the output video. This also applies to text watermarks.

      • Percentage value: The value is a percentage of the width and height of the output video. The value must be a number greater than 0 and up to 1, accurate to four decimal places.

        Important

        If the aspect ratio of the output video is variable and cannot be controlled, set the watermark position and size parameters as percentages.

        For example, 0.9999. Calculation example: Width/Video width = 0.1. Height/Video height = 0.06. Dx/Video width = 0.02. Dy/Video height = 0.03.

    • Default values

      • If you do not set the width and height of the watermark: The watermark width is set to 12% of the output video width. The watermark height is scaled to maintain the aspect ratio of the source watermark image.

      • If you set only the width or height: The specified dimension is used. The other dimension is scaled to maintain the aspect ratio of the source watermark image. For example, if you set Width to 44 and the aspect ratio of the source image is 2:1, the height is set to 22.

      • If you set both the width and height: The specified dimensions are used for the watermark.

      • If you do not set Dx and Dy: The default value 0 is used.

    Step 2: Create a transcoding template group and associate the watermark template

    Video watermarking is based on transcoding. Transcoding jobs are initiated based on a transcoding template group. You can associate multiple watermark templates with a single transcoding template.

    Using the console

    1. Log on to the ApsaraVideo VOD console.

    2. In the left-side navigation pane, choose Configuration Management > Media Processing > Transcoding Template Groups.

    3. Click Create Transcoding Template Group. The Add Transcoding Template Group page appears.

    4. Set a name for the transcoding template group.

    5. In the Audio and Video Transcoding Template or Audio and Video Packaging Template area on the left, click Add Template. You can then configure the transcoding parameters and enable image and text watermarks.

      • Watermark Template: Select one or more watermark templates that you created in Step 1.

      • Keep the default values for other parameters or change them as needed. For more information about the parameters and configuration suggestions, see Transcoding templates.

    6. You can click Save to create the transcoding template group.

      After the transcoding template group is created, you can view the group and its ID on the Transcoding Template Groups page.

    Using the OpenAPI

    Call the AddTranscodeTemplateGroup operation to create a transcoding template group. In the TranscodeTemplateList parameter, specify the WatermarkIds parameter to associate watermark template IDs.

    Step 3 (Optional): Create a workflow and associate the transcoding template group

    A workflow lets you orchestrate media processing tasks, such as transcoding, content moderation, and snapshotting, in a specific order. When you upload a media file or trigger a workflow, the media file is automatically processed based on the predefined task flow. You can create workflows only in the ApsaraVideo VOD console. For more information, see Workflows.

    Using the console

    1. Log on to the ApsaraVideo VOD console.

    2. In the left-side navigation pane, choose Configuration Management > Media Processing > Workflows.

    3. Click Add Workflow Template. The Add Workflow page appears.

    4. Enter a name for the workflow.

    5. Add or edit workflow nodes in the workflow topology.

      For example, to add a Transcode node, click + next to the Start node and select Transcode . Click the edit icon on the Transcode node. Customize the Node Name. From the Transcoding Template Groups list, select the transcoding template group that you created in Step 2.

    6. Click OK to create the workflow.

      After the workflow is created, you can view the workflow and its ID on the Workflow Management page.

    Step 4 (Optional): Configure transcoding event notifications

    Before you start a transcoding job, you can configure event notifications for ApsaraVideo VOD. This lets you receive callback messages that contain the status and result of the transcoding job after it is complete. For more information about how to configure event notifications, see Event notifications.

    The following event notification types are related to transcoding:

    Step 5: Start a watermarking transcoding job

    ApsaraVideo VOD lets you trigger transcoding when you upload media or process media. You can start transcoding based on a transcoding template group or a workflow that contains a media transcoding node.

    Using the console

    Scenario 1: Automatically trigger a watermarking job during upload

    1. Log on to the ApsaraVideo VOD console.

    2. In the left-side navigation pane, choose Media Files > Audio/Video.

    3. Click Upload Audio/Video, click Add Audio/Video, and select parameters such as the upload method and storage address. Then, for media processing, either select Use Transcoding Template Group and specify the transcoding template group that you created in Step 2, or select Use Workflow and specify the workflow that you created in Step 3.

      For more information about supported formats and parameter descriptions for uploads, see Upload files in the ApsaraVideo VOD console.

    4. After you add the videos, click Upload.

      After the video is uploaded, it is automatically transcoded based on the specified transcoding template group or workflow.

    Scenario 2: Manually trigger a watermarking job after upload

    1. Log on to the ApsaraVideo VOD console.

    2. In the left-side navigation pane, choose Media Files > Audio/Video.

    3. On the Audio/Video page, click Processing in the Actions column for the desired video.

    4. Based on your requirements, you can either select Use Transcoding Template Group and specify the transcoding template group that you created in Step 2, or select Use Workflow and specify the workflow that you created in Step 3.

    5. Click OK.

    Using the OpenAPI

    Scenario 1: Automatically trigger a watermarking job during upload

    null

    The CreateUploadVideo operation is used only to obtain an upload URL and credentials and to create basic media asset information. It does not upload the file. You must implement the upload logic. For a complete example of how to upload a file, see Upload media files using ApsaraVideo VOD APIs.

    When you call the Get upload URL and credentials for audio/video or UploadMediaByURL operation to upload an audio or video file, you can specify a processing method. To use a transcoding template group, set the TemplateGroupId parameter to the ID of the group that you created in Step 2. To use a workflow, set the WorkflowId parameter to the ID of the workflow that you created in Step 3. After the file is uploaded, ApsaraVideo VOD automatically transcodes it based on your selection.

    Scenario 2: Manually trigger a watermarking job after upload

    • To start transcoding based on a transcoding template group, call the SubmitTranscodeJobs operation and set the TemplateGroupId parameter to the ID of the transcoding template group that you created in Step 2.

    • To start transcoding based on a workflow, call the SubmitWorkflowJob operation and set the WorkflowId parameter to the ID of the workflow that you created in Step 3.

    Step 6: Get the result

    Asynchronous result notifications

    If you have configured event notifications, you can receive callback messages for Single Transcoding Job Complete or All Transcoding Jobs Complete to obtain information about the watermarking transcoding job.

    Synchronous queries

    Using the console

    1. Log on to the ApsaraVideo VOD console.

    2. In the left-side navigation pane, choose Media Files > Audio/Video.

    3. On the Audio/Video page, you can check the Status of the target video.

      A video Status of Normal indicates that the transcoding job was successful.

    4. Click Manage in the video's row to open the Basic Information page.

    5. Click the Video URL tab to view the transcoded video streams and obtain their playback URLs.

    Using the OpenAPI

    You can periodically poll the execution status and result of a transcoding job using its ID. The following operations are related to transcoding jobs:

    Application examples

    This section provides examples of how to use ApsaraVideo VOD for common watermarking scenarios, such as setting multiple watermarks and dynamically replacing watermark content using APIs.

    Short video copyright statement: Dynamic text watermark replacement

    Scenario description

    In short video applications, when a video uploaded by a user to a short video platform is downloaded or shared by other users, the video usually carries the logo of the short video platform and the ID or nickname of the original creator.

    Expected result

    A watermark that combines an image with text content that is unique to each user.

    文字水印特效

    Procedure

    1. Create two watermark templates: an image watermark template for the platform logo and a text watermark template for the creator's ID or nickname. For more information, see Step 1: Create a watermark template.

    2. Create a transcoding template group and associate the two watermark templates that you created in the previous step. For more information, see Step 2: Create a transcoding template group and associate the watermark template.

    3. Call the SubmitTranscodeJobs operation to start a transcoding job. When you start the job, use the OverrideParams parameter with the WatermarkId and Content parameters to overwrite the text content of the specified watermark template.

      • Example of the OverrideParams parameter: {"Watermarks":[{"WatermarkId":"The ID of the image watermark template"},{"WatermarkId":"The ID of the text watermark template","Content":"The text to replace the original watermark content"}]}

      • Design the trigger logic for the transcoding job as needed. For example, you can trigger transcoding when a user uploads a video. During transcoding, the ID or nickname of the original video creator is automatically retrieved and used to replace the content of the text watermark.

    Video website brand promotion: Dynamic image watermark replacement

    Scenario description

    A video website obtains the copyright of a film or TV series and then sub-licenses it to multiple other video websites. The videos distributed on each video website must display that website's brand logo.

    Expected result

    Image watermarks vary among video websites.

    水印

    Procedure

    1. Call the GetAuxiliaryUploadAddressAndAuth operation to upload the watermark images (brand logos of each video website) to ApsaraVideo VOD. For more information about how to upload a file, see Upload media files using ApsaraVideo VOD APIs.

    2. Create an image watermark template and set the watermark image to a brand logo. For more information, see Step 1: Create a watermark template.

    3. Create a transcoding template group and associate the image watermark template that you created in the previous step. For more information, see Step 2: Create a transcoding template group and associate the watermark template.

    4. Call the SubmitTranscodeJobs operation to start a transcoding job. When you start the job, use the OverrideParams parameter with the WatermarkId and FileUrl parameters to overwrite the watermark image of the specified watermark template.

      • Example of the OverrideParams parameter: {"Watermarks":{"WatermarkId":"The ID of the image watermark template","FileUrl":"The URL of the image to replace the original watermark image"}}

      • Design the trigger logic for the transcoding job as needed. For example, you can trigger transcoding when a video is uploaded.

    FAQ

    Failure to add a watermark image in the ApsaraVideo VOD console with an 'unavailable image URL' error

    If you have configured an accelerated domain name in ApsaraVideo VOD, you must configure an HTTPS certificate for the domain name. For more information, see HTTPS secure acceleration.

    Related documents

    • To deter infringement, you can display the viewer's nickname or ID in real time during playback. You can use the marquee feature of ApsaraVideo Player SDK for this purpose. For more information, see Official components.