You can add text or image watermarks to an image stored in OSS by adding watermark parameters. This topic describes the parameters used to add watermarks to an image and provides examples on how to add watermarks to an image.

Parameters

Operation name: watermark

The following table describes the parameters you can configure.

  • Basic parameters
    Parameter Required Description Valid value
    t No

    The opacity of the text or image watermark.

    		 [0,100]

    Default value: 100. A value of 100 indicates that the watermark is opaque.
    g No

    The position of the watermark on the image.
    • nw: upper left
    • north: upper middle
    • ne: upper right
    • west: middle left
    • center: center
    • east: middle right
    • sw: lower left
    • south: lower middle
    • se: lower right
    The following figure shows the positions of watermarks based on coordinates.
    x No

    The horizontal margin, which is the horizontal distance between the watermark and the image edge. This parameter takes effect only when the watermark is on the upper left, middle left, lower left, upper right, middle right, or lower right of the image.

    		[0,4096]

    Default value: 10

    Unit: px
    y No The vertical margin, which is the vertical distance between the watermark and the image edge. This parameter takes effect only when the watermark is on the upper left, upper middle, upper right, lower left, lower middle, or lower right of the image. [0,4096]

    Default value: 10

    Unit: px
    voffset No The vertical offset from the middle line. When the watermark is in the middle left, center, or middle right of the image, you can designate the vertical offset of the watermark along the middle line. [-1000,1000]

    Default value: 0

    Unit: px

    You can use the horizontal margin, vertical margin, and vertical offset from the middle line to adjust the position of a watermark on an image. You can also use these parameters to adjust the watermark layout when the image has multiple watermarks.

    The following figure shows the positions of watermarks based on coordinates.origin
  • Image watermark parameters
    Parameter Required Description Valid value
    image Yes The complete name of the image watermark object. The object name must be encoded in Base64. For more information, see Watermark encoding.

    For example, if the panda.png watermark object is in the image folder of a bucket, the object name to encode is image/panda.png. The encoded object name is aW1hZ2UvcGFuZGEucG5n.

    Note You can use images only in the current bucket as watermark images.
    		The Base64-encoded string.
  • Parameters for watermark image preprocessing

    You can preprocess a watermark image by calling the Resize images, Custom crop, Indexed cut, Rounded rectangle, and Rotate operations. In addition, the P parameter is supported when you resize a watermark image.

    Parameter Description Valid value
    P The proportion of the resized watermark image to the source image. The value of this parameter specifies the scale percentage of the watermark from the source image. For example, if you set the parameter value to 10 for a source image of 100 × 100 pixels, the size of the watermark image is 10 × 10 pixels. If the source image is 200 × 200 pixels, the size of the watermark image is 20 × 20 pixels. [1,100]
  • Text watermark parameters
    Parameter Required Description Valid value
    text Yes The content of the text watermark. The text content must be encoded in Base64. For more information, see Watermark encoding. The Base64-encoded string. The string can be up to 64 characters in length.
    type No The font of the text watermark. The font name must be Base64 encoded. For more information about the supported fonts and the encoded strings for the fonts, see Font types and encoded strings.

    Default value: wqy-zenhei (encoded value: d3F5LXplbmhlaQ)
    color No The color of the text watermark. The valid values for this parameter are RGB color values. RGB color values. For example, 000000 indicates black, and FFFFFF indicates white.

    Default value: 000000. A value of 000000 indicates that the color of the text is black.
    size No The size of the text watermark. (0,1000]

    Default value: 40

    Unit: px
    shadow No The opacity of the shadow for the text watermark. [0,100]

    Default value: 0. A value of 0 indicates no shadows are added to the text.
    rotate No The degree by which the text is rotated clockwise. [0,360]

    Default value: 0. A value of 0 indicates that the text is not rotated.
    fill No Specifies whether to tile the source image with the text watermarks. 0 and 1
    • 1: The source image is tiled with the text watermarks.
    • 0: The default value, which indicates that source image is not tiled with the text watermarks.

    The following table describes the valid values of the type parameter and the encoded strings of these values.

    Parameter value Font name Encoded value
    wqy-zenhei WenQuanYi Zen Hei d3F5LXplbmhlaQ
    wqy-microhei WenQuanYi Micro Hei d3F5LW1pY3JvaGVp
    fangzhengshusong Fangzheng Shusong ZmFuZ3poZW5nc2h1c29uZw
    fangzhengkaiti Fangzheng Kaiti ZmFuZ3poZW5na2FpdGk
    fangzhengheiti Fangzheng Heiti ZmFuZ3poZW5naGVpdGk
    fangzhengfangsong Fangzheng Fangsong ZmFuZ3poZW5nZmFuZ3Nvbmc
    droidsansfallback DroidSansFallback ZHJvaWRzYW5zZmFsbGJhY2s
  • Text-and-image watermark parameters
    Parameter Required Description Valid value
    order No The order of the text watermark and image watermark. 0 and 1
    • 0: The image watermark is before the text watermark. This is the default value.
    • 1: The text watermark is before the image watermark.
    align No The alignment of the text watermark and image watermark. 0, 1, and 2
    • 0: The text watermark and the image watermark are aligned based on top alignment.
    • 1: The text watermark and the image watermark are aligned based on center alignment.
    • 2: The text watermark and the image watermark are aligned based on bottom alignment. This is the default value.
    interval No The spacing between the text watermark and image watermark. [0,1000]

    Default value: 0

    Unit: px

Watermark encoding

When you add watermarks to an image, the content, color, and font of a text watermark and the image name of an image watermark must be URL-encoded in Base64. Encoding method:

  1. Encode the content by using Base64.
  2. Replace part of the encoded string.
    • Replace the plus signs (+) in the result with hyphens (-).
    • Replace the forward slashs (/) in the result with underscores (_).
    • Omit the equal signs (=) that are at the end of strings in the result.

We recommend that you use URL-safe Baes64 encoding tools to encode the content, color, and font of a text watermark and the image name of an image watermark.

Note The encoded strings for watermarks can be used only as the parameters configured to add watermarks. Do not include the encoded strings for watermarks in the signature strings.

Usage notes

  • You can use watermark images only in the current bucket. Online or local images must be uploaded to the current bucket before these images can be used for watermarking.
  • Only PNG, JPG, and WebP watermark images are supported.
  • Traditional Chinese is not supported for text watermarks.
  • Before you add multiple watermarks to an image, take note of the following items:
    • You can add up to three watermarks to an image.
    • A watermark image can be repeatedly used. However, the watermark must be placed at different positions on the source image each time.
    • Positions of each watermark cannot completely overlap.

Examples

An image in the bucket named image-demo-oss-zhangjiakou in the China (Zhangjiakou) region is used in this example. The following URL is used to access the image over the Internet:

FAQ

How do I use online or local images as watermark images?

When OSS Image Processing (IMG) is used to add image watermarks to a source image, ensure that the watermark images and the source image are from the same bucket. Before you use online or local images to watermark a source image, upload the images to the bucket that contains the source image.