tencent cloud

Persistent Image Processing
Last updated: 2025-12-09 11:34:48
Persistent Image Processing
Last updated: 2025-12-09 11:34:48

Overview

Cloud Infinite provides a convenient image processing mechanism that enables a series of image processing operations on images stored in COS.
The image processing mechanism is divided into the following four methods:
Method
Category
Description
Processing during download
Synchronous processing
When accessing images, perform real-time processing by adding image processing parameters or image styles to the image URL.
Process upon upload
Synchronous processing
When uploading images, perform real-time processing by adding the Pic-Operations field to the request header and setting the appropriate image processing parameters. The processed images will be stored in COS.
Cloud data processing
Synchronous processing
Process existing images on COS using the same method as processing upon upload. Add the Pic-Operations field to the request header and set the appropriate image processing parameters. The processed images will be stored in COS.
Asynchronous task processing
Asynchronous processing
Process existing images on COS by creating an asynchronous image processing task. The processed images will be stored in COS.

Processing during Download

You can add image processing parameters to the image URL to synchronously retrieve the processed image when accessing it.

Request Syntax

GET /<ObjectKey>?<Image Processing Parameters> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: <GMT Date>
Authorization: <Auth String>

Example

Request

GET /filename.jpg?imageMogr2/format/png HTTP/1.1
Host: examplebucket-1250000000.cos.ap-chengdu.myqcloud.com
Date: Wed, 28 Oct 2015 20:32:00 GMT
Authorization: <Auth String>

Return

HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 565
Date: Fri, 10 Apr 2020 09:35:16 GMT
Last-Modified: Fri, 10 Apr 2020 09:35:05 GMT
x-cos-request-id: NWFjMzQ0MDZfOTBmYTUwXzZkZV8z****

Processing during Upload

The process upon upload feature helps users implement image processing during upload. You only need to add the Pic-Operations field to the request header and set the appropriate image processing parameters. This enables image processing during upload and saves both the original image and processing result to COS. Currently supports image processing for files under 32MB.

Request Syntax

The request packet for image upload is consistent with the COS V5 simple file upload API, with only additional image processing parameters at the request header.
PUT /<ObjectKey> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: <GMT Date>
Authorization: <Auth String>
Pic-Operations: <PicOperations>
Note:
COS simple file upload API, please see COS PUT Object documentation.
Authorization: A request header that carries authentication information and is used to verify the legitimacy of requests. The Pic-Operations header must be included in the signature information. For details, see the Request Signature documentation.
The QPS limit for persistent processing is 100. If you have higher requirements, please contact us.

Request Content

Pic-Operations is a JSON format string, with specific parameters as follows:
Parameter Name
Type
Required
Description
is_pic_info
Int
No
Whether to return original image information, 0 for no return, 1 for return, default is 0.
rules
Array
No
Processing rules, one rule corresponds to one processing result (currently supports five rules), leave blank to skip image processing.
Each item in the rules (JSON array) has the following specific parameters:
Parameter Name
Type
Required
Description
bucket
String
Yes
The name of the destination bucket for storing results, in the format of BucketName-APPID.
fileid
String
Yes
Storage path and name of the processed file.
When the fileid is the same as the ObjectKey, the processed file will overwrite the original file storage; when they are different, the original file and the processed file will be stored separately. Naming rules:
1. The name must be URL-encoded.
2. Paths starting with / are absolute paths. For example, when the fileid value is /p2/test2.jpg, it means a file named test2.jpg is stored in the p2 folder.
3. Paths not starting with / are relative paths. For example, when the fileid value is p2/test2.jpg, it means a new p2 folder is created in the folder where ObjectKey is located, and then a file named test2.jpg is stored in the p2 folder.
Note: Do not end with /, as this will result in an empty filename.
rule
String
Yes
Image processing parameters. If processed according to a specified style, it starts with style/, followed by the style name. For example, if the style name is test, the rule field should bestyle/test.

Returned Content

The detailed data content of the response body is as follows:
Parameter Name
Type
Description
UploadResult
Container
Image information
The content of UploadResult node:
Parameter Name
Type
Description
OriginalInfo
Container
Image information
ProcessResults
Container
Image processing result
The content of OriginalInfo node:
Node Name
Type
Description
Key
String
Original image filename
Location
String
Image path
ImageInfo
Container
Original image information
ETag
String
Original image ETag information (if the processed image overwrites the original image, it is the processed image ETag Information)
The content of ImageInfo node:
Node Name
Type
Description
Md5
String
Hash value, MD5 used to verify integrity, prevent duplicate uploads, and serves as a unique file identifier.
Format
String
Image format
Width
Int
Image width
Height
Int
Image height
Quality
Int
Image quality
Ave
String
Dominant color of the image, format: 0xRRGGBB (RR, GG, BB are hexadecimal numbers representing red, green, and blue colors)
FrameCount
Int
Number of frames in an image. Static images have 1 frame, while animated images have the corresponding number of frames.
BitDepth
Int
The number of bits per color channel in an image, reflects the color precision of the image.
VerticalDpi
Int
Vertical resolution
HorizontalDpi
Int
Horizontal resolution
The content of ProcessResults node:
Node Name
Type
Description
Object
Container
Each image processing result
The content of Object node:
Node Name
Type
Description
Key
String
File name
Location
String
Image path
Format
String
Image format
Width
Int
Image width
Height
Int
Image height
Size
Int
Image size
Quality
Int
Image quality
Ave
String
Dominant color of the image, format: 0xRRGGBB (RR, GG, BB are hexadecimal numbers representing red, green, and blue colors)
FrameCount
Int
Number of frames in an image. Static images have 1 frame, while animated images have the corresponding number of frames.
BitDepth
String
The number of bits per color channel in an image, reflects the color precision of the image.
VerticalDpi
Int
Vertical resolution
HorizontalDpi
Int
Horizontal resolution
ETag
String
Processed image ETag information.

Example

Request

PUT /filename.jpg HTTP/1.1
Host: examplebucket-1250000000.cos.ap-chengdu.myqcloud.com
Date: Wed, 28 Oct 2015 20:32:00 GMT
Authorization:q-sign-algorithm=sha1&q-ak=**********************************&q-sign-time=1497530202;1497610202&q-key-time=1497530202;1497610202&q-header-list=&q-url-param-list=&q-signature=**************************************
Pic-Operations: {"is_pic_info":1,"rules":[{"bucket":"examplebucket-1250000000","fileid":"test.png","rule":"imageMogr2/format/png"}]}
Content-Length: 64

[Object]

Return

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 645
Date: Tue, 03 Apr 2018 09:06:16 GMT
Status: 200 OK
x-cos-request-id: NWFjMzQ0MDZfOTBmYTUwXzZkZV8z****

<UploadResult>
        <OriginalInfo>
            <Key>filename.jpg</Key>
            <Location>examplebucket-1250000000.cos.ap-chengdu.myqcloud.com/filename.jpg</Location>
            <ETag>&quot;580cd6930444576523c25f86ce2af9b1fc2d5484&quot;</ETag>
            <ImageInfo>
                <Format>JPEG</Format>
                <Width>640</Width>
                <Height>427</Height>
                <Quality>100</Quality>
                <Ave>0xa18454</Ave>
                <Orientation>1</Orientation>
                <FrameCount>1</FrameCount>
            </ImageInfo>
        </OriginalInfo>
        <ProcessResults>
            <Object>
                <Key>test.png</Key>
                <Location>examplebucket-1250000000.cos.ap-chengdu.myqcloud.com/test.png</Location>
                <Format>png</Format>
                <Width>640</Width>
                <Height>427</Height>
                <Size>463092</Size>
                <Quality>100</Quality>
                <ETag>&quot;eaa4e3d8fd498bbc63be3b71c46b9c61f23e3f0c&quot;</ETag>
                <FrameCount>1</FrameCount>
            </Object>
        </ProcessResults>
</UploadResult>
Note:
Processing during upload supports COS V5 multipart upload features. When using the COS V5 Complete Multipart Upload interface, you only need to add the Pic-Operations field to the request header to enable image processing.
POST /<ObjectKey>?uploadId=UploadId HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: <GMT Date>
Content-length: <Size>
Authorization: <Auth String>
Pic-Operations: <PicOperations>
Note:
Note: For COS API details, please see COS Complete Multipart Upload documentation.

Processing in the cloud

The image processing API for object storage can process images already stored in COS and save the results back to COS.

Request Syntax

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: <PicOperations>

Request Content

Pic-Operations is a JSON format string, with specific parameters as follows:
Parameter Name
Type
Required
Description
is_pic_info
Int
No
Whether to return original image information, 0 for no return, 1 for return, default is 0.
rules
Array
No
Processing rules, one rule corresponds to one processing result (currently supports five rules), leave blank to skip image processing.
Each item in the rules (JSON array) has the following specific parameters:
Parameter Name
Type
Required
Description
bucket
String
No
The name of the destination bucket for storing results, in the format of BucketName-APPID. If not specified, it defaults to the current bucket.
fileid
String
Yes
Storage path and name of the processed file.
When the fileid is the same as the ObjectKey, the processed file will overwrite the original file storage; when they are different, the original file and the processed file will be stored separately. Naming rules:
1. Name needs to be URL-encoded.
2. Paths starting with / are absolute paths. For example, when the fileid value is /p2/test2.jpg, it indicates a file named test2.jpg is stored in the p2 folder.
3. Paths not starting with / are relative paths. For example, when the fileid value is p2/test2.jpg, it means a new p2 folder is created in the folder where ObjectKey is located, and then a file named test2.jpg is stored in the p2 folder.
4. Note: Do not end with /, as this will result in an empty filename.
rule
String
Yes
Processing parameters. See Object Storage Image Processing API. If processed with a specified style, start with style/, followed by the style name. For example, if the style name is test, the rule field should be style/test.

Returned Content

The detailed data content of the response body is as follows:
Parameter Name
Type
Description
UploadResult
Container
Image information
The content of UploadResult node:
Parameter Name
Type
Description
OriginalInfo
Container
Image information
ProcessResults
Container
Image processing result
The content of OriginalInfo node:
Node Name
Type
Description
Key
String
Original image file name
Location
String
Image path
ImageInfo
Container
Original image information
ETag
String
Original image ETag information (if the processed image overwrites the original image, it is the processed image ETag Information)
The content of ImageInfo node:
Node Name
Type
Description
Md5
String
Hash value, MD5 used to verify integrity, prevent duplicate uploads, and serves as a unique file identifier.
Format
String
Image format
Width
Int
Image width
Height
Int
Image height
Quality
Int
Image quality
Ave
String
Dominant color of the image, format: 0xRRGGBB (RR, GG, BB are hexadecimal numbers representing red, green, and blue colors)
FrameCount
Int
Number of frames in an image. Static images have 1 frame, while animated images have the corresponding number of frames.
BitDepth
Int
The number of bits per color channel in an image, reflects the color precision of the image.
VerticalDpi
Int
Vertical resolution
HorizontalDpi
Int
Horizontal resolution
The content of ProcessResults node:
Node Name
Type
Description
Object
Container
Each image processing result
The content of Object node:
Node Name
Type
Description
Key
String
File Name
Location
String
Image path
Format
String
Image format
Md5
String
Hash value, MD5 used to verify integrity, prevent duplicate uploads, and serves as a unique file identifier.
Width
Int
Image width
Height
Int
Image height
Size
Int
Image size
Quality
Int
Image quality
FrameCount
Int
Number of frames in an image. Static images have 1 frame, while animated images have the corresponding number of frames.
BitDepth
Int
The number of bits per color channel in an image, reflects the color precision of the image.
VerticalDpi
Int
Vertical resolution
HorizontalDpi
Int
Horizontal resolution
ETag
String
Processed image ETag information

Example

Request

POST /filename.jpg?image_process HTTP/1.1
Host: examplebucket-1250000000.cos.ap-chengdu.myqcloud.com
Date: Wed,18 Jan 2017 16:17:03 GMT
Authorization: q-sign-algorithm=sha1&q-ak=**********************************&q-sign-time=1497530202;1497610202&q-key-time=1497530202;1497610202&q-header-list=&q-url-param-list=&q-signature=**************************************
Pic-Operations: {"is_pic_info":1,"rules":[{"bucket":"examplebucket-1250000000","fileid":"test.png","rule":"imageMogr2/format/png"}]}
Content-Length: 64

Return

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 645
Date: Tue, 03 Apr 2018 09:06:16 GMT
Status: 200 OK
x-cos-request-id: NWFjMzQ0MDZfOTBmYTUwXzZkZV8z****

<UploadResult>
            <OriginalInfo>
                <Key>filename.jpg</Key>
                <Location>examplebucket-1250000000.cos.ap-chengdu.myqcloud.com/filename.jpg</Location>
                <ETag>&quot;eaa4e3d8fd498bbc63be3b71c46b9c61f23e3f0c&quot;</ETag>
                <ImageInfo>
                    <Format>JPEG</Format>
                    <Width>640</Width>
                    <Height>427</Height>
                    <Quality>100</Quality>
                    <Ave>0xa18454</Ave>
                    <Orientation>1</Orientation>
                    <FrameCount>1</FrameCount>
                </ImageInfo>
            </OriginalInfo>
            <ProcessResults>
                <Object>
                    <Key>test.png</Key>
                    <Location>examplebucket-1250000000.cos.ap-chengdu.myqcloud.com/test.png</Location>
                    <Format>png</Format>
                    <Width>640</Width>
                    <Height>427</Height>
                    <Size>463092</Size>
                    <Quality>100</Quality>
                    <ETag>&quot;eaa4e3d8fd498bbc63be3b71c46b9c61f23e3f0c&quot;</ETag>
                    <FrameCount>1</FrameCount>
                </Object>
            </ProcessResults>
</UploadResult>

Asynchronous Task Processing

You can create an image processing task to perform image processing asynchronously. After creating the task, you can obtain the image processing result via task callback or by querying the task ID. For details, see Asynchronous Image Processing.
Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback