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
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. - 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:
- Encode the content by using Base64.
- 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.
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:
- Add an image watermark
Take the following steps to configure parameters:
- Resize the source image example.jpg to 300 × 300 pixels:
resize,w_300,h_300
- Set the quality of the source image to 90%:
quality,q_90
- Add the image watermark panda.png:
watermark,image_cGFuZGEucG5n
(cGFuZGEucG5n is an encoded value for panda.png.) - Set the opacity of the image watermark to 90%:
t_90
- Set the position of the image watermark to lower right, the horizontal margin to 10
pixels, and the vertical offset from the middle line to 10 pixels:
g_se,x_10,y_10
The following URL is used to process the image: https://image-demo-oss-zhangjiakou.oss-cn-zhangjiakou.aliyuncs.com/example.jpg?x-oss-process=image/resize,w_300,h_300/quality,q_90/watermark,image_cGFuZGEucG5n,t_90,g_se,x_10,y_10
- Resize the source image example.jpg to 300 × 300 pixels:
- Preprocess the image watermark and add it to the source image
Take the following steps to configure parameters:
- Resize the source image example.jpg to 300 pixels wide:
resize,w_300
- Resize the image watermark panda.png to 30% of the original size:
image_cGFuZGEucG5nP3gtb3NzLXByb2Nlc3M9aW1hZ2UvcmVzaXplLFBfMzA
(cGFuZGEucG5nP3gtb3NzLXByb2Nlc3M9aW1hZ2UvcmVzaXplLFBfMzA
is a Base64 encoded value forpanda.png? x-oss-process=image/resize,P_30
.) - Set the opacity of the image watermark to 90%, the position of the image watermark
to lower right, the horizontal margin to 10 pixels, and the vertical offset from the
middle line to 10 pixels:
t_90,g_se,x_10,y_10
- Resize the source image example.jpg to 300 pixels wide:
- Add a text watermark
Take the following steps to configure parameters:
- Resize the source image example.jpg to 300 × 300 pixels:
resize,w_300,h_300
- Set the text font of the text watermark to WenQuanYi Zen Hei:
type_d3F5LXplbmhlaQ
(d3F5LXplbmhlaQ is a Base64 encoded value for WenQuanYi Zen Hei.) - Use "Hello World" as the text content:
text_SGVsbG8gV29ybGQ
- Set the color of the text watermark to white and the size of the text to 30 pixels:
color_FFFFFF,size_30
- Set the opacity of the shadow of the text watermark to 50%:
shadow_50
- Set the position of the text watermark to lower right, the horizontal margin to 10
pixels, and the vertical offset from the middle line to 10 pixels:
g_se,x_10,y_10
- Resize the source image example.jpg to 300 × 300 pixels:
- Add a text-and-image watermark
Take the following steps to configure parameters:
- Resize the source image example.jpg to 300 × 300 pixels:
resize,w_300,h_300
- Set the quality of the source image to 90%:
quality,q_90
- Resize the image watermark panda.png to 30% of the original size:
image_cGFuZGEucG5nP3gtb3NzLXByb2Nlc3M9aW1hZ2UvcmVzaXplLFBfMzA
- Use "Hello World" as the text content:
text_SGVsbG8gV29ybGQ
- Set the color of the text watermark to white, the opacity of the shadow to 50%, the
position of the text watermark to lower right, the horizontal margin to 10 pixels,
and the vertical offset from the middle line to 10 pixels:
g_se,x_10,y_10,color_FFFFFF,shadow_50
- Specify that the image watermark is before the text watermark. Set the spacing between
the text watermark and image watermark to 10 pixels:
order_0,interval_10
- Set the text watermark and the image watermark to be aligned based on bottom alignment:
align_2
- Set the opacity of the text-and-image watermark to 100%:
t_100
The following URL is used to process the image: https://image-demo-oss-zhangjiakou.oss-cn-zhangjiakou.aliyuncs.com/example.jpg?x-oss-process=image/resize,w_300,h_300/quality,q_90/watermark,image_cGFuZGEucG5nP3gtb3NzLXByb2Nlc3M9aW1hZ2UvcmVzaXplLFBfMzA,text_SGVsbG8gV29ybGQ,order_0,interval_10,align_2,t_100,g_se,x_10,y_10,color_FFFFFF,shadow_50 - Resize the source image example.jpg to 300 × 300 pixels:
- Add multiple watermarks to the source image
If you want to add multiple watermarks to the source image, use forward slashes (/) to separate the operation performed to configure each watermark. Add multiple watermarks to an image, including four different text watermarks and five image watermarks. Three different image watermarks are used.
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.