imgWaterMarker-Documentation-Kingsoft Cloud

Standard Storage Service (KS3)

View more results

Document title with current keyword not found

Operation

imgWaterMarker

Description

Kingsoft Cloud provides three types of watermarks, including text watermarks, image watermarks, and mixed watermarks. If you have the read permission on an image, you can add a watermark to the image.
By adding a watermark, you can make a personalized image or indicate the source and copyright information of the image.

Note

Permission

To call this operation, you must have the GetObject permission. If the object does not exist, the following errors may be returned:

If you have the ListBucket permission on the bucket where the object resides, KS3 returns a 404 error. If you do not have the ListBucket permission on the bucket, KS3 returns a 403 error.

Image watermark

The URL of the source watermark image must start with http. If it starts with https, KS3 returns a 400 error. During the style encoding of some watermarks that contain Chinese characters, special characters such as plus signs (+) and forward slashes (/) must be escaped in the URL. Otherwise, the watermark cannot be accessed. The following table describes the special characters, their meanings in a URL, the escaping method, and the corresponding escape characters.

Special character	Meaning in a URL or escaping method	Escape character (an ASCII code preceded by the percent sign %)
+	Indicates a space.	%2B
Space	Each space in a URL can be replaced with a plus sign (+) or an escape character.	%20
/	Separates a directory from its subdirectory.	%2F
?	Separates a URL from a parameter.	%3F
*	Indicates a special character.	%25
#	Indicates a bookmark.	%23
&	Separates parameters.	%26
=	Specifies the value of a parameter.	%3D

Requests

Text watermark

Syntax

Note: The request syntax does not contain spaces or line breaks. The following syntax format is only for easy reading.

https://BucketName.${Endpoint of the bucket}/object@base@
    tag=imgWaterMarker
    &type=2
    &text=<base64EncodeText>
    &font=<base64EncodeFont>
    &fontsize=<base64EncodeFontSize>
    &fill=<base64EncodeFill>
    &dissolve=<dissolve>
    &gravity=<gravity>
    &dx=<offsetX>
    &dy=<offsetY>   HTTP/1.1
Host: BucketName.${Endpoint of the bucket}

Request parameters

Parameter	Required	Description
tag	Yes	The tag of the operation.
type	Yes	The type of the watermark. The value 2 indicates the text watermark.
text	Yes	The text in the watermark. The value is encoded by using URL-safe Base64 encoding.
font	No	The font of the text in the watermark. The value is encoded by using URL-safe Base64 encoding. The default font is SimHei.
fontsize	No	The font size in twips, with 1 twip equal to 1/20 point. The value is an integer and the default value is 500.
fill	No	The color of the text watermark. The value is encoded by using URL-safe Base64 encoding. You can set the color to RGB values, a color name such as black, or a hexadecimal value such as ## FF0000. For more information, see the RGB table.
dissolve		The opacity of the watermark. Valid values: 1 to 100. Default value: 100. The value 100 indicates that the watermark is completely opaque.
gravity		The position of the watermark. For more information, see the following watermark anchor parameter table. The default value is SouthEast, which indicates that the watermark is at the lower-right side.
dx		The horizontal (x-axis) distance between the right edges of the watermark and the image, in pixels. Default value: 10.
dy		The vertical (y-axis) distance between the bottom edges of the watermark and the image, in pixels. Default value: 10.
q	No	The relative quality of the JPG image during source image compression. Default value: 90. Valid values: 0: the highest compression ratio and lowest quality. 100: the lowest compression ratio and highest quality.
rotate	No	The rotation angle of the text watermark. Valid values: -180 to 180. Default value: 0.
tile	No	Specifies whether to tile the entire image with the text watermark. Default value: 0. Valid values: 1: tiles the entire image with the text watermark. 0: does not tile the entire image with the text watermark.
uw	No	The unit width at which the text watermark fills the image. Default value: 1.
uh	No	The unit height at which the text watermark fills the image. Default value: 1

Watermark anchor parameters

NorthWest	North	NorthEast
West	Center	East
SouthWest	South	SouthEast

Request header

The request does not require a special header.

Image watermark

Syntax

Note: The request syntax does not contain spaces or line breaks. The following syntax format is only for easy reading.

https://BucketName.ks3-cn-beijing.ksyuncs.com/object@base@
    tag=imgWaterMark  
    &type=1  
    &dissolve=<dissolve>  
    &gravity=<gravity>  
    &image=<base64EncodeImageURI>  
    &dx=<offsetX>  
    &dy=<offsetY>
    &wtw=<width>
    &wth=<height>   HTTP/1.1
Host: BucketName.ks3-cn-beijing.ksyuncs.com

Request parameters

Parameter	Required	Description
tag	Yes	The tag of the operation.
type	Yes	The type of the watermark. The value 1 indicates the image watermark.
image	Yes	The URL of the source watermark image. The value is encoded by using URL-safe Base64 encoding. Make sure that this URL returns an image.
dissolve		The opacity of the watermark. Valid values: 1 to 100. Default value: 100. The value 100 indicates that the watermark is completely opaque.
gravity		The position of the watermark. For more information, see the following watermark anchor parameter table. The default value is SouthEast, which indicates that the watermark is at the lower-right side.
dx		The horizontal (x-axis) distance between the right edges of the watermark and the image, in pixels. Default value: 10.
dy		The vertical (y-axis) distance between the bottom edges of the watermark and the image, in pixels. Default value: 10.
q	No	The relative quality of the JPG image during source image compression. Default value: 90. Valid values: 0: the highest compression ratio and lowest quality. 100: the lowest compression ratio and highest quality.
wtw	No	The watermark width threshold. If the width of an image watermark is less than this value, the image watermark is not added. Unit: pixels. The threshold must be an integer greater than 0.
wth	No	The watermark height threshold. If the height of an image watermark is less than this value, the image watermark is not added. Unit: pixels. The threshold must be an integer greater than 0.

Watermark anchor parameters

NorthWest	North	NorthEast
West	Center	East
SouthWest	South	SouthEast

Request header

The request does not require a special header.

Response

Response header

Header	Required	Description
Content-Type	Yes	The MIME type. If the request is successful, the value is image/, which is the fixed MIME type. If the request fails, the value is* application/json**.

Response body

If the request is successful, KS3 returns the binary image data.

If the request failed, KS3 returns the following JSON string:

{
    "errorCode": <HttpCode int>,
    "tipInfo": <ErrorTipInfo String>,
}

Operation-specific errors

HTTP status code	Description
400	The request format is incorrect.
404	The specified resource does not exist.
403	The access is denied.
500	An internal server error occurred.

Examples

This section provides some simple examples of watermarking.