Watermark

Last updated:2021-09-14 16:17:55

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

  1. 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.

  1. 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}/[email protected]@
	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/[email protected]@
	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.

Text watermark example

Sample request
  • Watermark text: Kingsoft Cloud
    • Original watermark text=Kingsoft Cloud
    • Encrypted watermark text (Base64)=6YeR5bGx5LqR
    • text=6YeR5bGx5LqR
  • Watermark text font: Microsoft YaHei
    • Original text font=Microsoft YaHei
    • Encrypted watermark font (Base64)=5b6u6L2v6ZuF6buR
    • font=5b6u6L2v6ZuF6buR
  • Watermark text color: ## bf1717 (Red)
    • Original font color=## bf1717
    • Encrypted font color (Base64)=I2JmMTcxNw==
    • fill=I2JmMTcxNw==
  • Watermark font size: 500 twips
    • fontsize=500
    • Watermark position: upper-right corner
    • gravity=NorthEast
  • Watermark opacity: 65%
    • dissolve=65
  • Horizontal distance between the right edges of the watermark and the image: 10
    • dx=10
  • Vertical distance between the bottom edges of the watermark and the image: 10
    • dy=10
Request code

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

https://ks3-cn-beijing.ksyuncs.com/ks3-resources/[email protected]@
	tag=imgWaterMark
	&type=2
	&dissolve=65
	&gravity=NorthEast
	&text=6YeR5bGx5LqR
	&font=5b6u6L2v6ZuF6buR
	&fill=I2JmMTcxNw==
	&fontsize=500
	&dy=10
	&dx=20
Sample response

Text watermark example

Image watermark example

Sample request
  • Watermark URL
    http://ks3-cn-beijing.ksyuncs.com/ks3-resources/fixed_ksc_logo.png

    • Source image URI=
      http://ks3-cn-beijing.ksyuncs.com/ks3-resources/fixed_ksc_logo.png
    • Encrypted URI (Base64)=aHR0cDovL2tzMy5rc3l1bi5jb20vY3NzL2ltZy9maXhlZF9rc2NfbG9nby5wbmc=
    • image=aHR0cDovL2tzMy5rc3l1bi5jb20vY3NzL2ltZy9maXhlZF9rc2NfbG9nby5wbmc=
  • Watermark position: upper-right corner

    • gravity=NorthEast
  • Watermark opacity: 65%

    • dissolve=65
  • Horizontal distance between the right edges of the watermark and the image: 10

    • dx=10
  • Vertical distance between the bottom edges of the watermark and the image: 10

    • dy=10
Request code

Note:

  • The request code does not contain spaces or line breaks. The following code format is only for easy reading.
  • When you make an image watermark, make sure that the URL of the source watermark image starts with http. Otherwise, KS3 returns a 400 error.
https://ks3-cn-beijing.ksyuncs.com/ks3-resources/[email protected]@
	tag=imgWaterMark   
	&type=1   
	&dissolve=65   
	&gravity=NorthEast   
	&image=aHR0cDovL2tzMy5rc3l1bi5jb20vY3NzL2ltZy9maXhlZF9rc2NfbG9nby5wbmc=   
	&dy=10   
	&dx=10   
Sample response

Image watermark example

Mixed watermark example

Sample request

When you make a mixed watermark, you can perform two or more operations (basic image operations and image watermarking) on the same image. You need to separate these operations with a vertical bar (|).

  • The width is 200 pixels, and the height is 150 pixels.
  • Watermark URL
    http://ks3-cn-beijing.ksyuncs.com/ks3-resources/fixed_ksc_logo.png
  • Watermark position: lower-right corner
    • gravity=SouthEast
  • Watermark opacity: 65%
    • dissolve=65
  • Horizontal distance between the right edges of the watermark and the image: 10
    • dx=10
  • Vertical distance between the bottom edges of the watermark and the image: 10
    • dy=10
Request code

Note:

  • The request code does not contain spaces or line breaks. The following code format is only for easy reading.
  • When you make an image watermark, make sure that the URL of the source watermark image starts with http. Otherwise, KS3 returns a 400 error.
https://ks3-cn-beijing.ksyuncs.com/ks3-resources/[email protected]@
	tag=imgBaseOp   
	&mode=0   
	&h=160   
	&w=220   
	|tag=imgWaterMark   
	&type=1   
	&dissolve=65   
	&gravity=NorthEast   
	&image=aHR0cDovL2tzMy5rc3l1bi5jb20vY3NzL2ltZy9maXhlZF9rc2NfbG9nby5wbmc=   
	&dy=10   
	&dx=10
    |tag=imgWaterMark   
    &type=1   
    &dissolve=65   
    &gravity=SouthEast   
    &image=aHR0cDovL2tzMy5rc3l1bi5jb20vY3NzL2ltZy9maXhlZF9rc2NfbG9nby5wbmc=   
    &dy=10   
    &dx=10   
Sample response

Mixed watermark example

Image watermark threshold example

Sample request
  • Watermark URL
    http://ks3-cn-beijing.ksyuncs.com/ks3-resources/fixed_ksc_logo.png
    • Source image URI=
      http://ks3-cn-beijing.ksyuncs.com/ks3-resources/fixed_ksc_logo.png
    • Encrypted URI (Base64)=aHR0cDovL2tzMy5rc3l1bi5jb20vY3NzL2ltZy9maXhlZF9rc2NfbG9nby5wbmc=
    • image=aHR0cDovL2tzMy5rc3l1bi5jb20vY3NzL2ltZy9maXhlZF9rc2NfbG9nby5wbmc=
  • Watermark position: upper-right corner
    • gravity=NorthEast
  • Watermark opacity: 65%
    • dissolve=65
  • Horizontal distance between the right edges of the watermark and the image: 10
    • dx=10
  • Vertical distance between the bottom edges of the watermark and the image: 10
    • dy=10
  • Width threshold: 500
    • wtw=500
  • Height threshold: 500
    • wth=500
Request code

Note:

  • The request code does not contain spaces or line breaks. The following code format is only for easy reading.
  • When you make an image watermark, make sure that the URL of the source watermark image starts with http. Otherwise, KS3 returns a 400 error.
https://ks3-cn-beijing.ksyuncs.com/ks3-resources/[email protected]@
	tag=imgWaterMark   
	&type=1   
	&dissolve=65   
	&gravity=NorthEast   
	&image=aHR0cDovL2tzMy5rc3l1bi5jb20vY3NzL2ltZy9maXhlZF9rc2NfbG9nby5wbmc=   
	&dy=10   
	&dx=10
	&wtw=500
	&wth=500   
Sample response

Image watermark threshold example

Did you find the above information helpful?

Unhelpful
Mostly Unhelpful
A little helpful
Helpful
Very helpful

What might be the problems?

Insufficient
Outdated
Unclear or awkward
Redundant or clumsy
Lack of context for the complex system or functionality

More suggestions

0/200

Please give us your feedback.

Submitted

Thank you for your feedback.

问题反馈