Docs

Torch Object Storage

Image processing

Watermark

The watermark feature allows you to add text, image, or image-text watermarks to images stored in TOS buckets. This topic introduces the parameters and provides examples of the watermark feature.

Constraints and limitations

Text watermarking does not currently support traditional Chinese characters.

For limitations on the format and size of watermark images, see the Constraints and limitations section in Overview.

Once a watermark is applied, both the original image and the watermark become static.

Adding a watermark using an SSE-C-encrypted image is currently not supported.

Basic parameters

The basic parameters apply to both text and image watermarks. The following table lists these parameters.

Parameter	Description	Value	Required
t	Opacity of the text or image watermark.	Range: [0,100] Default: 100. The watermark will be fully opaque.	No
g	Location of the watermark in an image.	nw: Top left north: Top center ne: Top right west: Center left center: Center east: Center right sw: Bottom left south: Bottom center se (Default): Bottom right	No
x	The horizontal margin, or the horizontal distance between the watermark and the edge of the image. This parameter only applies when the watermark is set to top left, center left, bottom left, top right, center right, or bottom right.	Range: [0,4096] Default: 10 Unit: px	No
y	The vertical margin, or the vertical distance between the watermark and the edge of the image. This parameter only applies when the watermark position is set to top left, top center, top right, bottom left, bottom center or bottom right.	Range: [0,4096] Default: 10 Unit: px	No
voffset	Vertical offset from the middle line. This parameter can be used to move the watermark up or down from the center line when the watermark is in the center, center left, or center right.	Range: [-1000,1000] Default: 0 Unit: px	No

Image watermark parameters

The following table lists the parameters for image watermarks. Use the parameters to preprocess watermark images.

tip

To add an image watermark, the value of the image parameter must be encoded using URL-safe Base64. For example, to use "watermark.jpg" as watermark image, the encoded value would be: image/watermark,image_d2F0ZXJtYXJrLmpwZw.

Parameter	Description	Value	Required
image	Filename of the watermark image, which must be encoded in URL-safe Base64. The watermark image must be in the same bucket as the original image.	A Base64-encoded string.	Required for adding an image watermark
P	The ratio of the watermark size to the size of the original image. This parameter is a special resize parameter that can only be used to preprocess watermark images.	A percentage. Example: When p = 10 and the original image size is 100x100, the watermark size is 10x10. If the original image size is 200x200, then the watermark size is 20x20.	No
Others	Other parameters used to preprocess the watermark image.	Resizing, cropping, indexed cropping, or rotation can be performed on the image.	No

warning

As part of the "image" parameter, the preprocessing parameters must also be encoded using URL-safe Base64. For example, to use "watermark.jpg" as watermark image and resize it to 30%, first form the parameter string as image_watermark.jpg?x-tos-process=image/resize,P_30. After encoding, the final value becomes image_d2F0ZXJtYXJrLmpwZz94LXRvcy1wcm9jZXNzPWltYWdlL3Jlc2l6ZSxQXzMw.

Text watermark parameters

The following table lists the parameters for text watermarks. Use the parameters to specify the content, font, font size, and font color for a text watermark.

tip

For example, to use "Hello world" as watermark text, select Fāng Zhèng Shū Sòng as the font, and rotate the watermark 45 degrees clockwise, first form the parameter string as text_Hello world,type_fangzhengshusong,rotate_45. After the text content and font are encoded using URL-safe Base64, the final value becomes text_SGVsbG8gd29ybGQ,type_ZmFuZ3poZW5nc2h1c29uZw,rotate_45.

Parameter	Description	Value	Required
text	Content of the text watermark, which must be encoded in URL-safe Base64.	The string to encode can contain up to 64 characters.	Required for adding a text watermark
type	Font of the text watermark, which must be encoded in URL-safe Base64.	The available options are WenQuanYi Zen Hei (the default option), WenQuanYi Micro Hei, Fāng Zhèng Shū Sòng, Fāng Zhèng Kǎi Tǐ, Fāng Zhèng Hēi Tǐ, Fāng Zhèng Fǎng Sòng, and DroidSansFallback. See the table below for more information on font encoding.	No
color	Color of the text watermark.	A hexadecimal color code ranging from 000000 to FFFFFF. The default is 000000 (black).	No
size	Size of the text watermark.	Range: (0,1000] Default: 40 Unit: px	No
shadow	Shadow opacity of the text watermark.	Range: [0,100] Default: 0. No shadow will be added to the text.	No
rotate	Degree of the clockwise rotation of the text watermark.	Range: [0,360] Default: 0. The watermark will not be rotated.	No
fill	Specifies whether to fill the original image with the text watermark.	1: Yes. 0 (Default): No.	No

The following table lists the supported font types for the type parameter and their corresponding URL-safe Base64 encodings.

Original value	URL-safe Base64 encoding	Font	Remarks
wqy-zenhei	d3F5LXplbmhlaQ	WenQuanYi Zen Hei	The padding character (=) is omitted.
wqy-microhei	d3F5LW1pY3JvaGVp	WenQuanYi Micro Hei	None.
fangzhengshusong	ZmFuZ3poZW5nc2h1c29uZw	Fāng Zhèng Shū Sòng	The padding character (=) can be omitted.
fangzhengkaiti	ZmFuZ3poZW5na2FpdGk	Fāng Zhèng Kǎi Tǐ	The padding character (=) can be omitted.
fangzhengheiti	ZmFuZ3poZW5naGVpdGk	Fāng Zhèng Hēi Tǐ	The padding character (=) can be omitted.
fangzhengfangsong	ZmFuZ3poZW5nZmFuZ3Nvbmc	Fāng Zhèng Fǎng Sòng	The padding character (=) can be omitted.
droidsansfallback	ZHJvaWRzYW5zZmFsbGJhY2s	DroidSansFallback	The padding character (=) can be omitted.

Text-image watermark parameters

You can use the following parameters to specify an image and text for watermarking and to arrange them.

Parameter	Description	Value	Required
order	Order of the watermark text and image.	0 (Default): Places the image in front of the text. 1: Places the text in front of the image.	No
align	Alignment mode of text and image watermarks.	0: Aligns text and image watermarks along their top edges. 1: Aligns text and image watermarks along their centers. 2 (Default): Aligns text and image watermarks along their bottom edges.	No
interval	Margin between the text and image watermarks.	Range: [0,1000] Default: 0 Unit: px	No

Examples

tip

Both the image and text watermark parameters must be Base64-encoded. We recommend using the base64url encoder to encode these parameters.

Adding text watermarks

Add the text watermark "Hello". Set the font size to 72, the color to red, and the font to fangzhengshusong.

https://tos-tools.tos-cn-beijing.volces.com/misc/sample.png?x-tos-process=image/watermark,text_SGVsbG8,size_72,color_FF0000,type_ZmFuZ3poZW5nc2h1c29uZw

Add the text watermark to the middle of the page. Rotate it 45 degrees clockwise and keep the other parameters unchanged.

https://tos-tools.tos-cn-beijing.volces.com/misc/sample.png?x-tos-process=image/watermark,text_SGVsbG8,size_72,color_FF0000,type_ZmFuZ3poZW5nc2h1c29uZw,g_center,rotate_45

Add the text watermark to cover the entire image while keeping the other parameters unchanged.

https://tos-tools.tos-cn-beijing.volces.com/misc/sample.png?x-tos-process=image/watermark,text_SGVsbG8,size_72,color_FF0000,type_ZmFuZ3poZW5nc2h1c29uZw,g_center,rotate_45,fill_1

Adding image watermarks

Watermark image: https://tos-tools.tos-cn-beijing.volces.com/misc/watermark1.png

Proportionally resize the original image to 60%. Then, add the watermark image and resize it to 10%. Finally, encode the parameter string misc/watermark1.png?x-tos-process=image/resize,p_10 to bWlzYy93YXRlcm1hcmsxLnBuZz94LXRvcy1wcm9jZXNzPWltYWdlL3Jlc2l6ZSxwXzEw.

https://tos-tools.tos-cn-beijing.volces.com/misc/sample.png?x-tos-process=image/resize,p_60/watermark,image_bWlzYy93YXRlcm1hcmsxLnBuZz94LXRvcy1wcm9jZXNzPWltYWdlL3Jlc2l6ZSxwXzEw

Add the image watermark to the middle of the original image. Rotate it 45 degrees clockwise and keep the other parameters unchanged.

https://tos-tools.tos-cn-beijing.volces.com/misc/sample.png?x-tos-process=image/resize,p_60/watermark,image_bWlzYy93YXRlcm1hcmsxLnBuZz94LXRvcy1wcm9jZXNzPWltYWdlL3Jlc2l6ZSxwXzEw,g_center,rotate_45

Adding text-image watermarks

tip

You can add a watermark that contains both images and text, and you can arrange them using the following parameters.

Add a text-image watermark and use the default values.

https://tos-tools.tos-cn-beijing.volces.com/misc/sample.png?x-tos-process=image/resize,p_60/watermark,image_bWlzYy93YXRlcm1hcmsxLnBuZz94LXRvcy1wcm9jZXNzPWltYWdlL3Jlc2l6ZSxwXzEw,text_SGVsbG8

Add a text-image watermark and align the text on the left and the image on the right along their central axes. Leave a 100-pixel margin between them.

https://tos-tools.tos-cn-beijing.volces.com/misc/sample.png?x-tos-process=image/resize,p_60/watermark,image_bWlzYy93YXRlcm1hcmsxLnBuZz94LXRvcy1wcm9jZXNzPWltYWdlL3Jlc2l6ZSxwXzEw,text_SGVsbG8,align_1,order_1,interval_100

Adding multiple images and text as watermarks

Add the image watermarks "watermark1.png" and "watermark2.png" and the text watermarks "Hello World" and "你好." Specifically:

Proportionally resize the original image to 60%.

Hello World: Set the font size to 60, the font to fangzhengshusong, and the color to 000000 (black). Place it in the upper-right corner.

你好: Set the font size to 50, the font to fangzhengkaiti, and the color to FF0000 (red). Place it in the middle.

watermark1.png: Proportionally resize it to 5%, place it in the lower-left corner, set the opacity to 60, and encode the parameter string misc/watermark1.png?x-tos-process=image/resize,p_5 to bWlzYy93YXRlcm1hcmsxLnBuZz94LXRvcy1wcm9jZXNzPWltYWdlL3Jlc2l6ZSxwXzU=.

watermark2.png: Proportionally resize it to 5%, place it in the lower-right corner, and encode the parameter string misc/watermark2.png?x-tos-process=image/resize,p_5 to bWlzYy93YXRlcm1hcmsyLnBuZz94LXRvcy1wcm9jZXNzPWltYWdlL3Jlc2l6ZSxwXzU=.

https://tos-tools.tos-cn-beijing.volces.com/misc/sample.png?x-tos-process=image/resize,p_60/watermark,image_bWlzYy93YXRlcm1hcmsxLnBuZz94LXRvcy1wcm9jZXNzPWltYWdlL3Jlc2l6ZSxwXzU=,g_sw/watermark,image_bWlzYy93YXRlcm1hcmsyLnBuZz94LXRvcy1wcm9jZXNzPWltYWdlL3Jlc2l6ZSxwXzU=,g_se/watermark,text_SGVsbG8gV29ybGQ,g_ne,size_60,type_ZmFuZ3poZW5nc2h1c29uZw/watermark,text_5L2g5aW9,g_center,size_50,type_ZmFuZ3poZW5na2FpdGk,color_FF0000

Last updated: 2026.08.20 17:53:16