Intelligent Image Cropping

Last updated: 2025-09-09 20:02:20

Intelligent Image Cropping

Last updated: 2025-09-09 20:02:20

Feature Description
Tencent Cloud Data Vision performs intelligent cropping on images through the AIImageCrop API, supporting persistence, on-cloud processing, and processing during download.
Note:
This interface is a GET request and uses a synchronous request method. It requires carrying a signature. For specific signature settings, please see Request Signature.
Authorization Description
When using with a sub-account, corresponding permissions need to be granted. For COS permissions, please refer to COS action. For CI permissions, please refer to CI action.
Processing during download: Set action to authorization policy as cos:GetObject, ci:CreateAIImageCropJob.
Process upon upload: Set action to authorization policy as cos:PutObject.
Cloud data processing: In the authorization policy, set action to cos:GetObject and cos:PutObject (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 requires enabling Cloud Infinite in advance and binding a bucket.
Use Limits
When using this API, please first confirm the relevant restrictions. For details, see Usage Limits.
Fee Description
This API is a paid service. Incurred fees will be charged by Cloud Infinite. For detailed billing instructions, see Content recognition.
﻿
Processing Method 1: Processing during Download
Request
 Original images are stored in COS.
GET /<ObjectKey>?ci-process=AIImageCrop&width=<width>&height=<height>&fixed=<fixed> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: <GMT Date>
Authorization: <Auth String>
 Original images come from other links.
GET /?ci-process=AIImageCrop&width=<width>&height=<height>&fixed=<fixed>&detect-url=<detect-url> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: <GMT Date>
Authorization: <Auth String>
Request Content
Operation name: AIImageCrop
Parameter
Meaning
Type
Required or Not
ObjectKey
object filename, for example: folder/document.jpg
String
No
ci-process
Cloud Infinite processing capability AIImageCrop fixed as
String
Yes
detect-url
You can process any publicly accessible image link by filling in detect-url. If detect-url is not filled in, the backend will default to processing ObjectKey. If detect-url is filled in, the backend will process the detect-url link, and there is no need to fill in ObjectKey.
http://www.example.com/abc.jpg needs to be url-encoded, and the processed result is http%3A%2F%2Fwww.example.com%2Fabc.jpg
String
No
width
The width of the cropping area, jointly composed with height, forms the desired image aspect ratio; enter a number greater than 0 and less than the image width in pixels.
Integer
Yes
height
The height of the cropping area, together with the width, jointly composes the desired image aspect ratio; the input number should be greater than 0 and less than the pixel value of the image height; the recommended value for width:height is between [1, 2.5], exceeding this range may affect the effect.
Integer
Yes
fixed
Whether to strictly output according to the values of width and height
When the value is 0, the aspect ratio (width : height) will be simplified to the lowest terms. For example, if the width input is 10 and the height input is 20, it will be simplified to 1:2.
value is 1, the output image's width equals width and height equals height; default value is 0
Integer
No
ignore-error
When this parameter is set to 1, for scenarios where processing fails due to a file being too large, the original image will be returned directly without error.
Integer
No
Response
HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 98645
Date: Tue, 23 Apr 2022 09:06:16 GMT
Status: 200 OK
Server: tencent-ci
x-cos-request-id: NWFjMzQ0MDZfOTBmYTUwXzZkZV8z****
﻿
[pic-content]
The processed image is returned directly in the response body.
Examples
Request
GET /filename.jpg?ci-process=AIImageCrop&width=<width>&height=<height>&fixed=<fixed> HTTP/1.1
Host: examplebucket-1250000000.cos.ap-chengdu.myqcloud.com
Date: Tue, 23 Apr 2022 09:06:16 GMT
Authorization: <Auth String>
Response
HTTP/1.1 200 OK
Content-Type: image/jpg
Content-Length: 98645
Date: Tue, 23 Apr 2022 09:06:16 GMT
Status: 200 OK
Server: tencent-ci
x-cos-request-id: NWFjMzQ0MDZfOTBmYTUwXzZkZV8z****
﻿
[pic-content]
Processing Method 2: Process Upon Upload
Request
Request Syntax
PUT  /<ObjectKey> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Authorization: Auth String
Pic-Operations: <PicOperations>
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 document.
Request header.
This API only uses common request headers. For details, see the Common Request Headers document. 
 In addition to common headers, the following headers need to be passed in:
Header Name
Description
Type
Pic-Operations
Parameters for image operations
String
Pic-Operations is a json format string with the following specific parameters:
Parameter Name
Description
Type
Required or Not
is_pic_info
Whether to return original image information, 0 means do not return original image information, 1 means return original image information, default is 0
Int
No
rules
Processing rules, one rule corresponds to one processing result (currently supports five rules), leave blank to not perform image processing
Array
No
Each item in the rules (json array) has the following specific parameters:
Parameter Name
Description
Type
Required or Not
bucket
Destination bucket name for storing results, format is BucketName-AppId, if not specified, it will be saved to the current bucket by default.
String
No
fileid
Storage path and name of the processed file. Rule description for naming.
For example, the file path and filename of the source object are: /p1/test1.jpg
Absolute paths start with /. For example, when the fileid value is /p2/test2.jpg, it means a file named test2.jpg is stored in the p2 folder.
Relative paths do not start with /. For example, when the fileid value is p2/test2.jpg, it means a new p2 folder is created in the p1 folder, and then a file named test2.jpg is stored in the p2 folder.
Do not end with /, otherwise an empty filename will occur
If you want the repaired image to overwrite the original image, set the fileid field to <ObjectKey>
String
Yes
rule
Process parameter
String
Yes
The processing parameters included in the rule are:
Parameter Name
Description
Type
Required or Not
ci-process
CI processing capability, intelligent cropping fixed as AIImageCrop
String
Yes
width
The width of the crop area, jointly composing the required image aspect ratio with height; Enter a number greater than 0 and less than the pixel value of the image width.
Integer
Yes
height
The height of the crop area, together with the width, jointly composes the desired image aspect ratio; the entered number must be greater than 0 and less than the pixel value of the image height; the recommended value for width : height is between [1, 2.5], exceeding this range may affect the effect
Integer
Yes
fixed
Whether to strictly output according to the values of width and height
When the value is 0, the aspect ratio (width : height) will be simplified to the lowest terms. For example, if the width input is 10 and the height input is 20, it will be simplified to 1:2.
value is 1, the output image's width equals width and height equals height; default value is 0
Integer
No
Request body.
The request body contains the original image [Image Content] to be cropped.
Response
Response Headers
This API returns common response headers. For details, please refer to the Common Response Headers document.
Response Body
The response body is returned with a content-type of application/xml. The specific data content is as follows:
Node Name (Keyword)
Parent Node
Description
Type
UploadResult
None.
Request result.
Container
The content of UploadResult
Node Name (Keyword)
Parent Node
Description
Type
OriginalInfo
UploadResult
Image information
Container
ProcessResults
UploadResult
Request processing result
Container
Content of OriginalInfo node
Node Name
Parent Node
Description
Type
Key
OriginalInfo
Original image filename
String
Location
OriginalInfo
path to the image
String
Etag
OriginalInfo
ETag value of the original image
String
ProcessResults node content
Node Name (Keyword)
Parent Node
Description
Type
Object 
ProcessResults
Processing result of each image
Container
Object node content
Node Name (Keyword)
Parent Node
Description
Type
Key
Object
Cropped image file name
String
Location
Object
Cropped image link
String
ETag
Object
ETag value of the cropped image
String
Size
Object
Size of the cropped image
Int
Examples
Request
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": "ci-process=AIImageCrop&width=<width>&height=<height>&fixed=<fixed>"
  }]
}
The processed image is stored in the bucket and uses the value of the field fileid as the object name.
Response
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 645
Date: Tue, 23 Apr 2022 09:06:16 GMT
Status: 200 OK
Server: tencent-ci
x-cos-request-id: NWFjMzQ0MDZfOTBmYTUwXzZkZV8z****
﻿
<UploadResult>
    <OriginalInfo>
        <Key>ObjectKey</Key>
        <Location>examplebucket-1250000000.cos.ap-chengdu.myqcloud.com/filename.jpg</Location>
        <ETag>"ed60e3598e6862d8c8443a06acfb2153"</ETag>
    </OriginalInfo>
    <ProcessResults>
        <Object>
            <Key>exampleobject</Key>
            <Location>examplebucket-1250000000.cos.ap-chengdu.myqcloud.com/exampleobject</Location>
            <Format/>
            <Size>354256</Size>
            <ETag>"521451f63c331becf533e466732c1091"</ETag>
        </Object>
    </ProcessResults>
</UploadResult>
Processing Method 3: Cloud Data Processing
Request
Request Syntax
POST  /<ObjectKey>?image_process HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Authorization: Auth String
Pic-Operations: <PicOperations>
Note:
Authorization: Auth String (See Request Signature document.)
Request header.
This API only uses common request headers. For details, see the Common Request Headers document. 
 In addition to common headers, the following headers need to be passed in:
Header Name
Description
Type
Pic-Operations
Parameters for image operations
String
Pic-Operations is a json format string with the following specific parameters:
Parameter Name
Description
Type
Required or Not
is_pic_info
Whether to return original image information, 0 means do not return original image information, 1 means return original image information, default is 0
Int
No
rules
Processing rules, one rule corresponds to one processing result (currently supports five rules), leave blank to not perform image processing
Array
No
Each item in the rules (json array) has the following specific parameters:
Parameter Name
Description
Type
Required or Not
bucket
Destination bucket name for storing results, format is BucketName-AppId, if not specified, it will be saved to the current bucket by default.
String
No
fileid
Storage path and name of the processed file. Rule description for naming.
For example, the source file path and name are: /p1/test1.jpg
Absolute paths start with /. For example, when the fileid value is /p2/test2.jpg, it means a file named test2.jpg is stored in the p2 folder.
Relative paths do not start with /. For example, when the fileid value is p2/test2.jpg, it means a new p2 folder is created in the p1 folder, and then a file named test2.jpg is stored in the p2 folder.
Note: Do not end with /, as it will result in an empty filename.
If you want the repaired image to overwrite the original image, set the fileid field to <ObjectKey>
String
Yes
rule
Process parameter
String
Yes
The processing parameters included in the rule are:
Parameter Name
Description
Type
Required or Not
ci-process
Cloud Infinite processing capability, intelligent cropping is fixed as AIImageCrop
String
Yes
width
The width of the cropping area, jointly composed with height, forms the required image aspect ratio; please enter a number greater than 0 and less than the pixel value of the image width.
Integer
Yes
height
Height of the cropping area, jointly composing the required image aspect ratio with width; Enter a number greater than 0 and less than the pixel value of the image height; The recommended value for width:height is between [1, 2.5], exceeding this range may affect the effect.
Integer
Yes
fixed
Whether to strictly output according to the values of width and height
When the value is 0, the aspect ratio (width : height) will be simplified to the lowest terms. For example, if the width input is 10 and the height input is 20, it will be simplified to 1:2.
value is 1, the output image's width equals width and height equals height; default value is 0
Integer
No
Request body.
Null
Response
Response Headers
This API returns common response headers. For details, please refer to the Common Response Headers document.
Response Body
The response body is returned with a content-type of application/xml. The specific data content is as follows:
Node Name (Keyword)
Parent Node
Description
Type
UploadResult
None.
Request result.
Container
The content of UploadResult
Node Name (Keyword)
Parent Node
Description
Type
OriginalInfo
UploadResult
Image information
Container
ProcessResults
UploadResult
Request processing result
Container
Content of OriginalInfo node
Node Name
Parent Node
Description
Type
Key
OriginalInfo
Original image filename
String
Location
OriginalInfo
path to the image
String
Etag
OriginalInfo
ETag value of the original image
String
ProcessResults node content
Node Name (Keyword)
Parent Node
Description
Type
Object
ProcessResults
Processing result of each image
Container
Object node content
Node Name (Keyword)
Parent Node
Description
Type
Key
Object
Cropped image file name
String
Location
Object
Cropped image link
String
ETag
Object
ETag value of the cropped image
String
Size
Object
Size of the cropped image
Int
Examples
Request
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: 
{
  "rules": [{
      "fileid": "exampleobject",
      "rule": "ci-process=AIImageCrop&width=<width>&height=<height>&fixed=<fixed>"
  }]
}
The processed image is stored in the bucket and uses the value of the field fileid as the object name.
Response
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 645
Date: Tue, 23 Apr 2022 09:06:16 GMT
Status: 200 OK
Server: tencent-ci
x-cos-request-id: NWFjMzQ0MDZfOTBmYTUwXzZkZV8z****
﻿
<UploadResult>
    <OriginalInfo>
        <Key>ObjectKey</Key>
        <Location>examplebucket-1250000000.cos.ap-chengdu.myqcloud.com/filename.jpg</Location>
        <ETag>"ed60e3598e6862d8c8443a06acfb2153"</ETag>
    </OriginalInfo>
    <ProcessResults>
        <Object>
            <Key>exampleobject</Key>
            <Location>examplebucket-1250000000.cos.ap-chengdu.myqcloud.com/exampleobject</Location>
            <Format/>
            <Size>354256</Size>
            <ETag>"521451f63c331becf533e466732c1091"</ETag>
        </Object>
    </ProcessResults>
</UploadResult>
﻿

Was this page helpful?

You can also Contact Sales or Submit a Ticket for help.

Yes

Feedback

Parameter	Meaning	Type	Required or Not
ObjectKey	object filename, for example: folder/document.jpg	String	No
ci-process	Cloud Infinite processing capability AIImageCrop fixed as	String	Yes
detect-url	You can process any publicly accessible image link by filling in detect-url. If detect-url is not filled in, the backend will default to processing ObjectKey. If detect-url is filled in, the backend will process the detect-url link, and there is no need to fill in ObjectKey. `http://www.example.com/abc.jpg` needs to be url-encoded, and the processed result is http%3A%2F%2Fwww.example.com%2Fabc.jpg	String	No
width	The width of the cropping area, jointly composed with height, forms the desired image aspect ratio; enter a number greater than 0 and less than the image width in pixels.	Integer	Yes
height	The height of the cropping area, together with the width, jointly composes the desired image aspect ratio; the input number should be greater than 0 and less than the pixel value of the image height; the recommended value for width:height is between [1, 2.5], exceeding this range may affect the effect.	Integer	Yes
fixed	Whether to strictly output according to the values of width and height When the value is 0, the aspect ratio (width : height) will be simplified to the lowest terms. For example, if the width input is 10 and the height input is 20, it will be simplified to 1:2. value is 1, the output image's width equals width and height equals height; default value is 0	Integer	No
ignore-error	When this parameter is set to 1, for scenarios where processing fails due to a file being too large, the original image will be returned directly without error.	Integer	No

Header Name	Description	Type
Pic-Operations	Parameters for image operations	String

Parameter Name	Description	Type	Required or Not
is_pic_info	Whether to return original image information, 0 means do not return original image information, 1 means return original image information, default is 0	Int	No
rules	Processing rules, one rule corresponds to one processing result (currently supports five rules), leave blank to not perform image processing	Array	No

Node Name (Keyword)	Parent Node	Description	Type
UploadResult	None.	Request result.	Container

Node Name	Parent Node	Description	Type
Key	OriginalInfo	Original image filename	String
Location	OriginalInfo	path to the image	String
Etag	OriginalInfo	ETag value of the original image	String

tencent cloud

Feature Description

Authorization Description

Service Activation

Use Limits

Fee Description

Processing Method 1: Processing during Download

Request

Request Content

Response

Examples

Request

Response

Processing Method 2: Process Upon Upload

Request

Request Syntax

Request header.

Request body.

Response

Response Headers

Response Body

Examples

Request

Response

Processing Method 3: Cloud Data Processing

Request

Request Syntax

Request header.

Request body.

Response

Response Headers

Response Body

Examples

Request

Response