imageScale-Documentation-Kingsoft Cloud

Standard Storage Service (KS3)

View more results

Document title with current keyword not found

Description

You can call this operation to resize, crop, and rotate an image, convert the format of the image, and gradually display the image.

Supported resizing options:

Resize an image based on the specified width and height
- Specify the width to which the image is to be resized and proportionally resize the image based on the width.
- Specify the height to which the image is to be resized and proportionally resize the image based on the height.
- Specify the width and height to which the image is to be resized and proportionally resize the image based on the longer side unless otherwise specified.
- Specify the width and height to which the image is to be resized and proportionally resize the image based on the shorter side unless otherwise specified.
- Specify the widths and heights of the image and the background, and fill the rest area. For BMP images, we recommend that you use the pipeline to fill the rest area.

Note: To enlarge an image, set the so parameter to 1. You do not need to set the so parameter if you enlarge the image in proportion.

Resize an image in proportion

Specify the percentage for image resizing. A percentage smaller than 100 indicates that the image is downsized, and a percentage greater than 100 indicates that the image is enlarged. Valid values: 1 to 1,000.

Limits for enlarging an image:

The maximum product of the pixel value of the longer side and the enlargement factor is 5,000.
If the image size is less than or equal to 1 MB, you can enlarge the image by at most 10 times (the maximum percentage you can specify is 1,000). If the image size is greater than 1 MB but less than or equal to 2 MB, you can enlarge the image by at most 5 times. If the image size is greater than 2 MB, you can enlarge the image by at most 3 times.

Supported cropping options

After the image is resized, perform centered cropping on the parts that exceed the predefined range. The option is available only after you specify the width and height to which the image is to be resized.
After you specify the fixed width and height, perform centered cropping based on the fixed width and height.
Crop an image by specifying the start horizontal and vertical coordinates, and the width and height to which the image is cropped.

Rotate an image

Rotate an image based on the rotation angle specified in the Exif information.

Convert the format of an image

You can specify the final format of an image. Supported formats: JPG, JPEG, PNG, GIF, WBMP, BMP, and WebP.

Note: The order of the preceding four operations is rotation, resizing, cropping, and format conversion, regardless of the parameter setting order.

Gradual display

Display methods for JPG and JPEG images:

Top-down scanning
Blurred first and gradually clear later (especially when the network environment is poor)

The first method is used by default. To use the second method, you must set the gradual display parameter.

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.

Request

Syntax

https://BucketName.${Endpoint of the bucket}/object@base@
    tag=imgScale   
    &m=<mode>   
    &w=<width>   
    &h=<height>   
    &q=<quality>   
    &F=<format>   
    &r=<auto-orient>   
    &c=<cut>   
    &f=<fixed>     
    &s=<strip>
    &cox=<x-coordinate>
    &coy=<y-coordinate>
    &rotate=<degree>
    &et=<extent>
    &etw=<extent width>
    &eth=<extent height>
    &etc=<extent colour>    
HTTP/1.1
Host: BucketName.${Endpoint of the bucket}

Request parameters

Parameter	Meaning	Required	Default value	Valid value	Description
tag	The tag of the operation.	Yes
m	The resizing mode.	No	0	0	The image is resized based on the resizing ratio of the longer side without cropping.
				1	The image is resized based on the resizing ratio of the shorter side without cropping.
				2	Proportionally resize the image by setting the minimum width of the resized image to <width> and the minimum height to <height>.
w	The width of the resized or cropped image.	Either w or h is required.		1-4096	Specifies the width of the resized or cropped image. Unit: pixels. If w is set and h is not set, the image is proportionally resized by width.
h	The height of the resized or cropped image.	Either w or h is required.		1-4096	Specifies the height of the resized or cropped image. Unit: pixels. If h is set and w is not set, the image is proportionally resized by height.
p	The percentage at which an image is resized.	No		1-1000	The percentage for image resizing. A value smaller than 100 specifies that the image will be downsized and a value greater than 100 specifies that the image will be enlarged. Limits for the value of p in the case of image enlarging: If the image size is less than or equal to 1 MB, you can enlarge the image by at most 10 times (the maximum value you can specify is 1,000). If the image size is greater than 1 MB but less than or equal to 2 MB, you can enlarge the image by at most 5 times. If the image size is greater than 2 MB, you can enlarge the image by at most 3 times. The maximum product of the pixel value of the longer side and the enlargement factor is 5,000.
so	Specifies whether to enlarge the image.	No	0	The value 1 specifies that the image will be enlarged.	Specifies whether to enlarge the image.
q	The output image quality.	No	75	0-100	The relative quality of the JPG image during source image compression. Valid values: 0: the highest compression ratio and lowest quality. 100: the lowest compression ratio and highest quality.
F	The format of the resized image.	No			By default, the format of the source image is used. Supported formats: JPG, JPEG, PNG, GIF, WBMP, BMP, and WebP.
r	The rotate mode.	No	0	0	Does not rotate the image.
				1	Rotates the image based on the rotation angle specified in the Exif information of the source image.
				2	Rotates the image based on the rotation angle that you specified in the <rotate> parameter.
c	Specifies whether to crop the image.	No	0	0	Does not crop the image.
c	Specifies whether to crop the image.	No	0	1	Crops the part of the image that exceeds the specified range after resizing. This option applies to proportional resizing based on the shorter side. The resized image will be cropped from top down and left to right based on the center line to obtain the image of the specified size.
f	Specifies whether to fix the width and height.	No	0	0	Does not fix the width and height.
f	Specifies whether to fix the width and height.	No	0	1	Crops the area with the specified width and height based on the center line of the image. This parameter is used along with the c parameter. When f is set to 1, the width and height of the image are fixed and cropping is performed without resizing.
s	Specifies whether metadata can be removed.	No	1	0	Metadata cannot be removed.
s	Specifies whether metadata can be removed.	No	1	1	Metadata can be removed.
cox	The start horizontal coordinate for cropping.	No	Centered cropping		This parameter is used along with the c and f parameters. If this parameter is not set, centered cropping is used by default.
coy	The start vertical coordinate for cropping.	No	Centered cropping		This parameter is used along with the c and f parameters. If this parameter is not set, centered cropping is used by default.
rotate	The rotation angle.	No	0	1-360	By default, the image is not rotated. To specify a custom rotation angle, you must first set the <r> parameter to 2.
et	Specifies whether to add a background.	No	0	0	Does not add a background.
et	Specifies whether to add a background.	No	0	1	Adds a background to fill the blank area after the image is resized.
etw	The width of the background.	No	The maximum width of the source image.	1-4096	Unit: pixels. If you do not set eth or etw, the maximum height and width of the source image is used by default to form a square. If you set only etw, the background height equals the height of the source image by default.
eth	The height of the background.	No	The maximum height of the source image.	1-4096	Unit: pixels. If you do not set eth or etw, the maximum height and width of the source image is used by default to form a square. If you set only eth, the background width equals the width of the source image by default.
etc	The color of the background.	No	FFFFFF		The RRGGBB values are supported. If the background is transparent, set the parameter to transparent. Supported image formats of the transparent background: PNG and GIF.
interlace	Specifies whether to save the image as a gradually displayed image.	No	0	0	Saves the image in the normal JPG or JPEG format.
interlace		No	0	1	Saves the image as a gradually displayed JPG or JPEG image.

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.

Operation-specific errors

HTTP status code	Description
400	The request format is incorrect.
404	The specified resource does not exist.
500	An internal server error occurred. If this error occurs, contact Kingsoft Cloud as soon as possible.

Examples

Specify the width to which the image is to be resized and proportionally resize the image based on the width

Set the width to 200 pixels

http://ks3-resources.ks3-cn-beijing.ksyuncs.com/suiyi.jpg@base@tag=imgScale&w=200

Image example

Specify the height to which the image is to be resized and proportionally resize the image based on the height

Set the height to 200 pixels

http://ks3-resources.ks3-cn-beijing.ksyuncs.com/suiyi.jpg@base@tag=imgScale&h=200

Image example

Specify the width and height to which the image is to be resized and proportionally resize the image based on the longer side unless otherwise specified

Set the height to 200 pixels and width to 100 pixels

http://ks3-resources.ks3-cn-beijing.ksyuncs.com/suiyi.jpg@base@tag=imgScale&h=200&w=100&m=0

Image example

Specify the width and height to which the image is to be resized and proportionally resize the image based on the shorter side unless otherwise specified

Set the height to 200 pixels, width to 100 pixels, and m to 1

http://ks3-resources.ks3-cn-beijing.ksyuncs.com/suiyi.jpg@base@tag=imgScale&h=200&w=100&m=1

Image example

Proportionally downsize the image

Proportionally downsize the image to 1/4 of its size

http://ks3-resources.ks3-cn-beijing.ksyuncs.com/suiyi.jpg@base@tag=imgScale&p=25

Image example

Proportionally enlarge the image based on the specified width

Set the height to 400 pixels and so to 1

http://ks3-resources.ks3-cn-beijing.ksyuncs.com/suiyi.jpg@base@tag=imgScale&w=400&so=1

Image example

After the image is resized, perform centered cropping on the parts that exceed the predefined range

Set the height to 30 pixels and width to 200 pixels

http://ks3-resources.ks3-cn-beijing.ksyuncs.com/suiyi.jpg@base@tag=imgScale&h=30&w=200&m=0&c=1

Image example

Set the height to 200 pixels and width to 20 pixels

http://ks3-resources.ks3-cn-beijing.ksyuncs.com/suiyi.jpg@base@tag=imgScale&h=200&w=20&m=1&c=1

Image example

After you specify the fixed width and height, perform centered cropping based on the fixed width and height

Set the height to 100 pixels and width to 50 pixels

http://ks3-resources.ks3-cn-beijing.ksyuncs.com/suiyi.jpg@base@tag=imgScale&h=100&w=50&c=1&f=1

Image example

Crop an image by specifying the start horizontal and vertical coordinates in the image, and the width and height to which the image is cropped

Set the start horizontal coordinate to 100, start vertical coordinate to 50, and the height and width to which the image is cropped respectively to 200 pixels and 100 pixels

http://ks3-resources.ks3-cn-beijing.ksyuncs.com/suiyi.jpg@base@tag=imgScale&w=100&h=200&c=1&f=1&cox=100&coy=50

Image example