You can add text or image watermarks to an image in Object Storage Service (OSS) by using Image Processing (IMG) parameters. This topic describes the parameters that you can use and provides examples on how to use the parameters to add watermarks to an image.

Usage notes

  • Only images in the bucket that stores the image you want to watermark can be used as watermarks. To use online or local images as watermarks, you must first upload the images to the bucket.
  • Only JPG, PNG, BMP, WebP, and TIFF images can be used as watermarks.
  • You can add up to three different image watermarks to a single image, and an image watermark cannot completely overlap with another image watermark.
  • Traditional Chinese characters cannot be used as text watermarks.

Parameters

Operation: watermark

The following tables describe the parameters that you can configure when you add watermarks to images.

  • Basic parameters
    ParameterRequiredDescriptionValue
    tNoThe opacity of the watermark. [0,100]

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

    gNoThe position of the watermark on the image. Default value: se.
    • 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.
    For the precise position that is specified by each value, see the following figure.
    xNoThe horizontal margin that specifies 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: pixel.

    yNoThe vertical margin that specifies 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: pixel.

    voffsetNoThe vertical offset from the middle line. When the watermark is in the middle left, center, or middle right of the image, you can specify the vertical offset of the watermark along the middle line. [-1000,1000]

    Default value: 0.

    Unit: pixel.

    fillNoSpecifies whether to tile the image watermarks or text watermarks across the image. Default value: 0.
    Note If you want to add tiled watermarks, submit an application at Quota Center..
    • 1: tiles the image watermarks or text watermarks across the image.
    • 0: does not tile the image watermarks or text watermarks across the image.
    padxNoThe horizontal spacing between watermarks when the source image is filled with the image watermarks or text watermarks. This parameter is valid only when you set fill to 1. [0,4096]

    Default value: 0.

    Unit: pixel.

    padyNoThe vertical spacing between watermarks when the source image is filled with the image watermarks or text watermarks. This parameter is valid only when you set fill to 1. [0,4096]

    Default value: 0.

    Unit: pixel.

    You can use x, y, and offset to adjust the position of a watermark on an image. You can also use these parameters to adjust the watermark layout when the image contains multiple watermarks.

    The following figure shows the positions of watermarks based on coordinates. origin
  • Image watermark parameters
    ParameterRequiredDescriptionValue
    imageYesThe complete name of the image object that you want to use as a watermark. The object name must be Base64-encoded. For more information, see Encode watermarks.

    For example, if you want to use an image object named panda.png in the image directory of the current bucket as a watermark, the object name to encode is image/panda.png and the encoded object name is aW1hZ2UvcGFuZGEucG5n.

    Note Only objects in the current bucket can be used as watermarks.
    		Base64-encoded strings.
  • Parameters for watermark image preprocessing

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

    ParameterDescriptionValue
    PThe size of the watermark image relative to the source image. The value of this parameter specifies the size of the watermark in percentage of the source image size. For example, if you set this parameter to 10 for a source image of 100 × 100 pixels, the size of the watermark image is 10 × 10 pixels. If the size of the source image is 200 × 200 pixels, the size of the watermark image is 20 × 20 pixels. [1,100]
  • Text watermark parameters
    ParameterRequiredDescriptionValue
    textYesThe content of the text watermark. The text content must be Base64-encoded. For more information, see Encode watermarks. A Chinese string cannot exceed 64 characters in length before the string is Base64-encoded.
    typeNoThe 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).

    colorNoThe color of the text watermark. The valid values for this parameter are RGB color values. For example, 000000 specifies black, and FFFFFF specifies white.

    Default value: 000000.

    sizeNoThe size of the text watermark. (0,1000]

    Default value: 40.

    Unit: pixel.

    shadowNoThe opacity of the shadow for the text watermark. [0,100]

    Default value: 0. A value of 0 specifies no shadows are added to the text.

    rotateNoThe degree by which the text is rotated clockwise. [0,360]

    Default value: 0. A value of 0 specifies that the text is not rotated.

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

    DescriptionFont nameEncoded value
    wqy-zenheiWenQuanYi Zen Heid3F5LXplbmhlaQ
    wqy-microheiWenQuanYi Micro Heid3F5LW1pY3JvaGVp
    fangzhengshusongFangzheng ShusongZmFuZ3poZW5nc2h1c29uZw
    fangzhengkaitiFangzheng KaitiZmFuZ3poZW5na2FpdGk
    fangzhengheitiFangzheng HeitiZmFuZ3poZW5naGVpdGk
    fangzhengfangsongFangzheng FangsongZmFuZ3poZW5nZmFuZ3Nvbmc
    droidsansfallbackDroidSansFallbackZHJvaWRzYW5zZmFsbGJhY2s
  • Text-and-image watermark parameters
    ParameterRequiredDescriptionValue
    orderNoThe order of the text watermark and image watermark. 0 and 1. Default value: 0.
    • 0: The image watermark is on the top of the text watermark.
    • 1: The text watermark is on the top of the image watermark.
    alignNoThe alignment of the text watermark and image watermark. 0, 1, and 2. Default value: 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.
    intervalNoThe spacing between the text watermark and image watermark. [0,1000]

    Default value: 0.

    Unit: pixel.

Encode watermarks

The content, color, and font of a text watermark and the name of an image watermark must be a URL-safe string that is Base64-encoded. Perform the following steps to encode watermarks:

  1. Encode the content by using Base64.
  2. Replace the following characters in the encoded string:
    • Replace the plus signs (+) in the encoded string with hyphens (-).
    • Replace the forward slashes (/) in the encoded string with underscores (_).
    • Omit the equal signs (=) at the end of the encoded string.

We recommend that you use base64url encoder to encode the content, color, and font of a text watermark and the name of an image watermark.

Important Encoded strings can be used only as parameters in specific watermark operations. Do not use encoded strings in signature strings.

Example 1: Add a text watermark to an image

You can use object URLs, OSS SDKs, or API operations to configure IMG parameters that are used to process images. In this example, object URLs are used. You can use object URLs to configure IMG parameters only for public-read images. If you want to configure IMG parameters for private images, use OSS SDKs or API operations. For more information, see IMG implementation modes.

This section provides examples on how to watermark an image named example.jpg in the oss-console-img-demo-cn-hangzhou-3az bucket. The image is hosted at the following URL: https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example.jpg.1

The following examples show how to add a text watermark to example.jpg:

Example 2: Add an image watermark to the source image

The following examples show how to add an image watermark to the example.jpg image:

Example 3: Add text and image watermarks to the source image

The following example shows how to add text and image watermarks to the example.jpg image:

The following URL is used to process the image based on the encoded results of the image that you want to add to the source image as an image watermark and the string that you want to add to the source image as a text watermark: https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example.jpg?x-oss-process=image/watermark,image_cGFuZGEucG5nP3gtb3NzLXByb2Nlc3M9aW1hZ2UvcmVzaXplLFBfMzA,text_SGVsbG8gV29ybGQ. 5

FAQ

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

When IMG is used to add image watermarks to a source image, make sure that the watermark images and the source image are stored in the same bucket. To add online or local images to a source image as image watermarks, you must first upload the images to the bucket in which the source image is stored.

What do I do if the "font content is too large" message appears when I add a text watermark?

When you add a text watermark to an image by using OSS IMG parameters, the maximum length of a text watermark cannot exceed 64 characters (One Chinese character is treated as three characters). When the "font content is too large" message appears, we recommend that you shorten the text watermark. For more information, see Example 1: Add a text watermark to an image.

What do I do if I fail to add an image watermark to a private object?

The URL of a private object is signed. IMG parameters cannot be added to a signed URL. If you want to process a private object, add IMG parameters to the signature. For more information, see Generate a signed URL that includes IMG parameters for an object.

Can I add a background color to an image watermark when I add the image watermark?

No, you cannot add a background color to an image watermark.

How do I use a signed URL to access an image?

The URL of a private object must be signed. IMG parameters cannot be added to a signed URL. If you want to process a private object, add IMG parameters to the signature. For more information, see IMG.