tencent cloud

Scaling
Last updated: 2025-12-08 17:29:45
Scaling
Last updated: 2025-12-08 17:29:45

Feature Overview

Cloud Infinite provides image scaling function through the imageMogr2 API. This feature supports the following processing methods:
Processing during download
Processing during upload
Processing in the cloud

Authorization Guide

When using with a sub-account, corresponding permissions must be granted to view all actions of Cloud Infinite.
Processing during download: Set action to cos:GetObject in the authorization policy.
Process upon upload: Set action to cos:PutObject in the authorization policy.
Cloud data processing: Set action to cos:PutObject in the authorization policy.
Note：
The resource corresponding to GetObject is the source file, and the resource corresponding to PutObject is the transferred file.

Service Activation

Using this feature will activate Cloud Infinite for you by default and bind a bucket. No role authorization is required, it can be used directly.

Use Limits

The GIF format does not support scaling up.
Additional usage limitations apply. For details, see Specifications and Limits.

Fee Description

This API is a paid service. The incurred fees will be collected by Cloud Infinite. For detailed billing information, see Image Processing Fees.
If processing during download is adopted and the download is performed via the public network, the API call will incur Traffic Fees.

API Example

Method One: Processing during Download

GET /<ObjectKey>?imageMogr2/thumbnail/<imageSizeAndOffsetGeometry> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: <GMT Date>
Authorization: <Auth String>

Method Two: Processing during Upload

PUT /<ObjectKey> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Authorization: Auth String
Pic-Operations: 
{
  "is_pic_info": 1,
  "rules": [{
      "fileid": "exampleobject",
      "rule": "imageMogr2/thumbnail/<imageSizeAndOffsetGeometry>"
  }]
}

Method Three: Processing in the cloud

POST /<ObjectKey>?image_process HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Content-length: Size
Authorization: Auth String
Pic-Operations: 
{
  "is_pic_info": 1,
  "rules": [{
      "fileid": "exampleobject",
      "rule": "imageMogr2/thumbnail/<imageSizeAndOffsetGeometry>"
  }]
}
Note:
Authorization: A request header that carries authentication information to verify the legitimacy of a request. The Pic-Operations header must be included in the signature information. For details, see the Request Signature documentation.
Pic-Operations is a JSON format string. For specific parameter details, refer to Persistent Image Processing.
When fileid is the same as ObjectKey, the processed image will overwrite the original image storage; if they are different, the original image and the processed image will be stored separately.
The value of fileid needs to be passed through URL-safe Base64 encoding.

Processing Parameter Description

Operation name: thumbnail.
Parameter
Meaning
Type
Required
ObjectKey
Object filename, for example folder/sample.jpg.
String
Yes
/thumbnail/!<Scale>p
Specify the width and height of the image as Scale% of the original image. The value range is integers from 1 to 1000. Values exceeding this range will not be processed.
String
No
/thumbnail/!<Scale>px
Specify the width of the image as Scale% of the original image. The height remains unchanged. The value range is integers from 1 to 1000. Values exceeding this range will not be processed.
String
No
/thumbnail/!x<Scale>p
Specify the height of the image as Scale% of the original image. The width remains unchanged. The value range is integers from 1 to 1000. Values exceeding this range will not be processed.
String
No
/thumbnail/<Width>x
Specify the width of the target image as Width. The height is proportionally scaled. The value range is integers from 1 to 10000. Values exceeding this range will be set to 10000.
String
No
/thumbnail/x<Height>
Specify the height of the target image as Height. The width is proportionally scaled. The value range is integers from 1 to 10000. Values exceeding this range will be set to 10000.
String
No
/thumbnail/<Width>x<Height>
Limit the maximum width and height of thumbnails to Width and Height respectively. Perform proportional scaling, with the ratio being the smaller value between the width scaling ratio and height scaling ratio. The value range for Width and Height is 1 - 10000. Values exceeding this range will be set to 10000.
Note:
Width scaling ratio: Target width / Original image width; Height scaling ratio: Target height / Original image height.
String
No
/thumbnail/!<Width>x<Height>r
Limit the minimum width and height of thumbnails to Width and Height respectively. Perform proportional scaling, with the ratio being the larger value between the width scaling ratio and height scaling ratio. The value range for Width and Height is 1 - 10000. Values exceeding this range will be set to 10000.
Note:
Width scaling ratio: Target width / Original image width; Height scaling ratio: Target height / Original image height.
String
No
/thumbnail/<Width>x<Height>>
Limit the maximum width and height of thumbnails to Width and Height respectively. Perform proportional scaling down, with the ratio being the smaller value between the width scaling ratio and height scaling ratio. The value range for Width and Height is 1 - 10000. Values exceeding this range will be set to 10000. If the target width (height) is larger than the original image width (height), no processing will be performed.
Note:
Width scaling ratio: Target width / Original image width; Height scaling ratio: Target height / Original image height.
String
No
/thumbnail/<Width>x<Height><
Limit the maximum width and height of thumbnails to Width and Height respectively. Perform proportional scaling up, with the ratio being the smaller value between the width scaling ratio and height scaling ratio. The value range for Width and Height is 1 - 10000. Values exceeding this range will be set to 10000. If the target width (height) is larger than the original image width (height), no processing will be performed.
Note:
Width scaling ratio: Target width / Original image width; Height scaling ratio: Target height / Original image height.
String
No
/thumbnail/<Width>x<Height>!
Ignore the original image's aspect ratio. Specify the image width as Width and height as Height. Forcefully scale the image, which may cause deformation of the target image. The value range for Width and Height is 1 - 10000. Values exceeding this range will be set to 10000.
String
No
/thumbnail/<Area>@
Scale the image proportionally, such that the total pixel count of the result does not exceed Area.
String
No
/pad/<pad>
Scale the original image to the largest size within a rectangle of specified Width and Height, then center it and fill the blank area with the color specified by the color parameter; take value 0 or 1.
0: disable pad mode
1: enable pad mode
String
No
/color/<color>
Fill color, <color> should be set in hexadecimal RGB format (e.g., #FF0000). For details, see RGB Color Codes Chart. The value must be converted into URL-safe Base64 encoding. The default value is #FFFFFF, which represents white.
String
No
/ignore-error/1
When processing requests carry this parameter, if operations fail due to oversized files or parameter exceeds limit, it will directly return the original image without reporting an error.
String
No
Note:
Among the multiple thumbnail parameters in the table, at least one must be selected. If multiple parameters are selected, only the first one will be processed. For example, if two parameters are selected: /thumbnail/!<Scale>p/!x<Scale>p, only !<Scale>p will take effect.

Practical Example

Note:
The examples in this documentation contain only processing during download. This type of processing will not save the processed images to the storage bucket. If you have a need to save, you can check the Persistent Image Processing document and configure process upon upload or cloud data processing.
Input image:




Case One: Scaling Width and Height

Assume the image width and height are scaled to 50% of the original image. The example is as follows:
http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?imageMogr2/thumbnail/!50p
The final effect is as follows:




Case Two: Scaling Width, Height Unchanged

Assume the specified image width is scaled to 50% of the original image while the height remains unchanged. The example is as follows:
http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?imageMogr2/thumbnail/!50px
The final effect is as follows:




Case Three: Pad Mode Scaling

Scale the original image to the largest size within a 600 x 600 rectangle and use the specified color to fill the blank parts. The example is as follows:
http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?imageMogr2/thumbnail/600x600/pad/1/color/IzNEM0QzRA
The final effect is as follows:




Case Four: Pad Mode Scaling with Private File Signature

Use the same processing method, only add the signature part, and connect it with the image processing parameters using "&". The example is as follows:
http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?q-sign-algorithm=<signature>&imageMogr2/thumbnail/!50px
Note:
<signature> is the signature part. To obtain it, please refer to Request Signature documentation.

Important Notes

To prevent unauthorized personnel from accessing and downloading the original image through links that do not carry processing parameters, you can include the processing parameters in the request signature. The processing parameters are the key in the overall parameters, with an empty value. A simple example is provided below (for reference only; the link may be expired and inaccessible). For detailed calculation methods, please refer to Request Signature.
http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?q-sign-algorithm=sha1&q-ak=**********************************&q-sign-time=1593342360;1593342720&q-key-time=1593342360;1593342720&q-header-list=&q-url-param-list=watermark%252f1%252fimage%252fahr0cdovl2v4yw1wbgvzlteyntewmdawmdqucgljc2gubxlxy2xvdwquy29tl3nodwl5aw4uanbn%252fgravity%252fsoutheast&q-signature=**************************************&watermark/1/image/aHR0cDovL2V4YW1wbGVzLTEyNTEwMDAwMDQucGljc2gubXlxY2xvdWQuY29tL3NodWl5aW4uanBn/gravity/southeast

Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback