You can add watermarks to images or objects that are stored in Object Storage Service (OSS) to help prevent the resources from being replicated or used without your authorization.
Scenarios
Copyright protection: To help stop your work from being replicated or used without your authorization, you can add watermarks to images to identify the copyright.
Brand promotion: Enterprises or individuals can add watermarks with brand logos or names to images, videos, or documents to promote their brands or logos.
Tamper prevention: Adding watermarks to official documents, certificates, or reports can increase the difficulty of tampering and reduce the risk of document forgery.
Image plagiarism prevention: Images can be easily downloaded and republished by Internet users. You can add watermarks to images to show they are copyrighted.
Legal compliance requirement: In some cases, you must add watermarks to meet legal compliance requirements when you publish specific content of legal terms or contract terms.
Usage notes
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.
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 six image watermarks to an image and image watermarks cannot completely overlap with each other.
Traditional Chinese characters cannot be used as text watermarks.
Parameters
Action: watermark
The following tables describe the parameters that you can configure when you add watermarks to images.
Basic parameters
Parameter
Required
Description
Valid value
t
No
The opacity of the watermark.
[0,100]
Default value: 100. A value of 100 specifies 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. This is the default value.
For the precise position that is specified by each value, see the following figure.
x
No
The 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.
y
No
The 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.
voffset
No
The vertical offset from the middle line. When the watermark is on 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.
fill
No
Specifies whether to tile the image watermarks or text watermarks across the image.
NoteIf 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. This is the default value.
padx
No
The horizontal spacing between watermarks when the image watermarks or text watermarks are tiled across the image. This parameter is valid only when you set fill to 1.
[0,4096]
Default value: 0.
Unit: pixel.
pady
No
The vertical spacing between watermarks when the image watermarks or text watermarks are tiled across the image. This parameter is valid only when you set fill to 1.
[0,4096]
Default value: 0.
Unit: pixel.
You can use x, y, and voffset 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.
Image watermark parameters
Parameter
Required
Description
Valid value
image
Yes
The 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 watermark-related parameters.
For example, if you want to use an image named panda.png in the image directory of the bucket as the watermark, you need to encode image/panda.png. The encoding result is
aW1hZ2UvcGFuZGEucG5n
.NoteOnly objects in the current bucket can be used as watermarks.
Base64-encoded strings.
Parameters for watermark image preprocessing
You can preprocess watermark images by using parameters in image resizing, custom crop, indexed slice, rounded rectangle, and image rotation actions. When you preprocess a watermark image, you can include the P parameter to resize the watermark image.
Parameter
Description
Valid value
P
The percentage of the size of the watermark image relative to the source image. 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
Parameter
Required
Description
Valid value
text
Yes
The content of the text watermark. The text content must be Base64-encoded. For more information, see Encode watermark-related parameters.
A Chinese string cannot exceed 64 characters in length before the string is Base64-encoded.
type
No
The font of the text watermark. The font name must be Base64-encoded.
For more information about the supported fonts and the encoding results of the fonts, see Font types and encoding results.
Default value: wqy-zenhei (encoding result: d3F5LXplbmhlaQ).
color
No
The 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.
size
No
The size of the text watermark.
(0,1000]
Default value: 40.
Unit: pixel.
shadow
No
The 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.
rotate
No
The 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 encoding results of these values.
Value
Description
Encoding result
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. 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.
align
No
The alignment of the text watermark and image watermark.
0, 1, and 2. Default value: 2.
0: Top alignment is applied to the text watermark and the image watermark.
1: Center alignment is applied to the text watermark and the image watermark.
2: Bottom alignment is applied to the text watermark and the image watermark.
interval
No
The spacing between the text watermark and image watermark.
[0,1000]
Default value: 0.
Unit: pixel.
Encode watermark-related parameters
When you add watermarks, you must use Base64 to encode watermark-related parameters, such as the text and font of the text watermark and the name of the watermark image into URL-safe strings. You need to perform the following steps to complete encoding:
Encode watermark-related parameters by using Base64.
Replace the following characters in the encoding result:
Replace the plus signs (+) in the encoding result with hyphens (-).
Replace the forward slashes (/) in the encoding result with underscores (_).
Omit the equal signs (=) at the end of the encoding result.
We recommend that you use base64url encoder to encode watermark-related parameters.
The encoding results can be used only in specific parameters in watermark operations. Do not use the encoding results in signature strings.
Example 1: Add a text watermark to an image
This section provides examples on how to watermark an image named example.jpg in the oss-console-img-demo-cn-hangzhou-3az bucket in the China (Hangzhou) region. The image is hosted at the following URL: https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example.jpg.
The following examples show how to add a text watermark to example.jpg:
Add the string "Hello World" to the image as a text watermark
Base64-encode the string "Hello World" into a URL-safe string. For more information, see Encode watermark-related parameters. The encoding result is
SGVsbG8gV29ybGQ
and the URL used to process the image is https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example.jpg?x-oss-process=image/watermark,text_SGVsbG8gV29ybGQ.Configure multiple IMG parameters when you add a text watermark to the image
In this example, IMG parameters are configured to perform the following operations on the source image and the text watermark "Hello World" that you want to add to the source image:
Resize the source image example.jpg to 300 × 300 pixels by using
resize,w_300,h_300
Set the font of the watermark text to WenQuanYi Zen Hei by using
type_d3F5LXplbmhlaQ
. d3F5LXplbmhlaQ is the encoding result that is obtained after WenQuanYi Zen Hei is Base64-encoded.Add the string "Hello World" to the source image as a text watermark by using
text_SGVsbG8gV29ybGQ
.Set the color of the watermark text to white and the size of the text to 30 pixels by using
color_FFFFFF,size_30
.Set the opacity of the shadow of the watermark text to 50% by using
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 by using
g_se,x_10,y_10
.
The following URL is used to process the image based on the preceding parameters: https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example.jpg?x-oss-process=image/resize,w_300,h_300/watermark,type_d3F5LXplbmhlaQ,size_30,text_SGVsbG8gV29ybGQ,color_FFFFFF,shadow_50,t_100,g_se,x_10,y_10.
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:
Add an image named panda.png to the source image as an image watermark
Base64-encode the name of the panda.png image into a URL-safe string. The encoding result is
cGFuZGEucG5n
and the URL used to process the image is https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example.jpg?x-oss-process=image/watermark,image_cGFuZGEucG5n.Configure multiple IMG parameters when you add an image watermark to the source image
In this example, IMG parameters are configured to perform the following operations on the source image and the image named panda.png that you want to add to the source image as an image watermark:
Resize the source image example.jpg to 300 × 300 pixels by using
resize,w_300,h_300
.Set the quality of the source image example.jpg to 90% by using
quality,q_90
.Add the panda.png image to the source image as an image watermark by using
watermark,image_cGFuZGEucG5n
. cGFuZGEucG5n is the encoding result that is obtained after the image name panda.png is Base64-encoded.Set the opacity of the watermark image to 90% by using
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 by using
g_se,x_10,y_10
.
The following URL is used to process the image based on the preceding parameters: https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.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.
Preprocess the image watermark and then configure IMG parameters
In this example, IMG parameters are configured to perform the following operations on the source image and the image named panda.png that you want to add to the source image as an image watermark:
Resize the width of the source image example.jpg to 300 pixels by using
resize,w_300
.Resize the image watermark panda.png to 30% of the size of the source image by using
image_cGFuZGEucG5nP3gtb3NzLXByb2Nlc3M9aW1hZ2UvcmVzaXplLFBfMzA
(cGFuZGEucG5nP3gtb3NzLXByb2Nlc3M9aW1hZ2UvcmVzaXplLFBfMzA
is the encoding result ofpanda.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 by using
t_90,g_se,x_10,y_10
.
The following URL is used to process the image based on the preceding parameters: https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example.jpg?x-oss-process=image/resize,w_300/watermark,image_cGFuZGEucG5nP3gtb3NzLXByb2Nlc3M9aW1hZ2UvcmVzaXplLFBfMzA,t_90,g_se,x_10,y_10.
Add multiple image watermarks to the source image
In this example, panda.png and Tulips.jpg are added to example.jpg as image watermarks.
Base64-encode the name of the panda.png image into a URL-safe string. The encoding result is
cGFuZGEucG5n
. Add the panda.png image as an image watermark by usingwatermark,image_cGFuZGEucG5n
.Base64-encode the name of the Tulips.jpg image into a URL-safe string. The encoding result is
VHVsaXBzLmpwZw
. Set the position of the image watermark to middle left, the horizontal margin to 10 pixels, and the vertical offset from the middle line to 10 pixels by usingwatermark,image_VHVsaXBzLmpwZw,g_west,x_10,y_10
.
The following URL is used to process the image based on the preceding parameters:
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 encoding results of the name 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.
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 must be signed. IMG parameters cannot be directly added to the end of a signed URL. If you want to process a private object, add IMG parameters to the signature. For more information, see Generate a signed object URL that includes IMG parameters.
Can I set a background color for an image watermark when I add the image watermark?
No, you cannot set a background color for 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 directly added to the end of a signed URL. If you want to process a private object, add IMG parameters to the signature. For more information, see IMG.
Does OSS support vertical arrangement of watermarks?
Yes, OSS supports vertical arrangement of watermarks. If you want to arrange watermarks vertically, you can split the watermarking operation into multiple watermarking operations and use multiple watermark operators to implement vertical watermark arrangement.
For example, you can use https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example.jpg?x-oss-process=image/watermark,text_SGVsbG8gV29ybGQ/watermark,text_SGVsbG8gV29ybGQy,y_60.