All Products
Search

This Product

    CDN:Add watermarks

    Document Center

    CDN:Add watermarks

    Last Updated:Apr 01, 2026

    The image editing feature of Alibaba Cloud CDN lets you overlay text and image watermarks on images served through CDN—without modifying the original files. Use watermarks to protect copyright, add branding, or apply signatures to your images.

    The image editing feature of Alibaba Cloud CDN, the image editing feature of Dynamic Content Delivery Network (DCDN), and the Image Processing (IMG) feature of Object Storage Service (OSS) are independent features and cannot be used interchangeably. Image editing is free of charge until further notice.

    How it works

    Watermarks are applied by appending an image_process query parameter to the image URL. Each watermark uses the watermark action, followed by its parameters. To apply multiple watermarks, chain multiple watermark actions with /.

    http(s)://example.com/image01.png?image_process=watermark,<param1>_<value1>,<param2>_<value2>/watermark,<param1>_<value1>

    All text content, font names, and image watermark URLs must be URL-safe Base64-encoded before use. See Encode watermark values.

    Limits

    • Each image supports up to five watermarks. Text and image watermarks can be combined.

    • Image watermarks cannot be resized. The source image used as a watermark must not exceed 1 MB.

    • When converting between image formats (for example, JPEG to WebP or PNG to WebP), the output file may be larger because different formats use different compression algorithms. To reduce file size after conversion, set the quality parameter.

    Parameters

    Basic parameters

    These parameters apply to both text and image watermarks.

    ParameterDescriptionDefaultRange
    tOpacity. 100 is fully opaque; 0 is fully transparent.100[0, 100]
    gPosition on the base image. See the position values table below.—See below
    xHorizontal margin in pixels. Applies when the watermark is at a left or right edge position (nw, west, sw, ne, east, se).10[0, 4096]
    yVertical margin in pixels. Applies when the watermark is at a top or bottom edge position (nw, north, ne, south, se).10[0, 4096]

    Position values for `g`:

    ValuePosition
    nwUpper left
    northUpper middle
    neUpper right
    westMiddle left
    centerCenter
    eastMiddle right
    swLower left
    southLower middle
    seLower right
    Watermark position diagram

    Use x and y together to fine-tune watermark placement, including when positioning multiple watermarks on the same image.

    Image watermark parameters

    ParameterDescriptionValue
    imageThe watermark image URL, URL-safe Base64-encoded. The URL must be publicly accessible. If the URL requires authentication or has access restrictions, CDN may fail to retrieve it.Base64-encoded string

    Text watermark parameters

    ParameterDescriptionDefaultRange
    textText content, URL-safe Base64-encoded.—Up to 60 characters in the Base64-encoded string
    typeFont name, URL-safe Base64-encoded. If the specified font is not one of the 10 supported fonts, alihyaihei is used.alihyaiheiSee font table below
    colorText color as a 6-digit RGB hex value.000000 (black)For example, FFFFFF for white
    sizeFont size in pixels.40(0, 1000]
    rotateClockwise rotation in degrees.0[0, 360]
    fillTiles the watermark across the entire base image. 1 enables tiling; 0 disables it.00 or 1

    Supported fonts:

    Font nameStyleEncoded value
    alihyaiheiBold (default)YWxpaHlhaWhlaQ
    hysongSongti variantaHlzb25n
    hyheiHeiti variantaHloZWk
    hyshuangxianDouble-lineaHlzaHVhbmd4aWFu
    comfortaaComfortaaY29tZm9ydGFh
    notosansNotoSansbm90b3NhbnM

    Encode watermark values

    All watermark content—text strings, font names, and image URLs—must be URL-safe Base64-encoded. Standard Base64 uses characters that are not safe in URLs, so two substitutions are required.

    To encode a watermark value:

    1. Base64-encode the value using a URL-safe Base64 encoding tool.

    2. Apply these character substitutions to the encoded output:

      • Replace + with -

      • Replace / with _

      • Remove any trailing = characters

    Important

    Use encoded watermark values only in watermark parameters. Do not include them in signature strings.

    Examples

    Text watermark

    Add the text "Hello World" in the Songti font (hysong):

    • "Hello World" encodes to SGVsbG8gV29ybGQ

    • hysong encodes to aHlzb25n

    http(s)://example.com/image01.png?image_process=watermark,text_SGVsbG8gV29ybGQ,type_aHlzb25n

    Combined text and image watermarks

    Apply two watermarks simultaneously—a text watermark at the lower right and an image watermark at the upper left:

    • Text watermark: "Hello World" → SGVsbG8gV29ybGQ, positioned at lower right with 10 px margins (g_se,x_10,y_10)

    • Image watermark: URL http://example-test.oss-ap-southeast-1.aliyuncs.com/image/shuiyin.png encodes to aHR0cDovL2V4YW1wbGUtdGVzdC5vc3MtYXAtc291dGhlYXN0LTEuYWxpeXVuY3MuY29tL2ltYWdlL3NodWl5aW4ucG5n, positioned at upper left with 10 px margins (g_nw,x_10,y_10)

    Multiple watermark actions are separated with /:

    http(s)://example.com/image01.png?image_process=watermark,text_SGVsbG8gV29ybGQ,g_se,x_10,y_10/watermark,image_aHR0cDovL2V4YW1wbGUtdGVzdC5vc3MtYXAtc291dGhlYXN0LTEuYWxpeXVuY3MuY29tL2ltYWdlL3NodWl5aW4ucG5n,g_nw,x_10,y_10

    Tiled watermark

    To tile a text watermark across the entire image, set fill to 1. Combine with rotate to angle the watermark:

    http(s)://example.com/image01.png?image_process=watermark,text_SGVsbG8gV29ybGQ,fill_1,rotate_30,t_50

    This tiles "Hello World" at a 30-degree angle with 50% opacity.