Persistent Image Processing

Last updated: 2021-07-27 16:00:44

    Processing upon Upload

    COS allows you to process images upon upload. To enable this, add the Pic-Operations request header and set the relevant parameters. You can also save the input images and processing results to COS. Currently, images within 20 MB can be processed.

    Sample request

    The request packet for uploading an image is the same as that of the API for simply uploading a COS V5 file. The only difference is that image processing parameters are added to the request packet header.

    PUT /<ObjectKey> HTTP/1.1
    Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
    Date: GMT Date
    Authorization: Auth String
    Pic-Operations: <PicOperations>
    
    Note:

    • API for simply uploading a COS file. For more information, see COS PUT Object.
      Authorization: Auth String. For more information, see Request Signature.
    • The QPS for Persistent Image Processing is limited to 100. For a higher QPS, please contact us.

    Request content

    Pic-Operations is JSON string. Its parameters are as follows:

    Parameter Type Required Description
    is_pic_info Int No Whether to return the input image information
    0 (default): no
    1: yes
    rules Array No Processing rules (up to 5 rules are supported). Each rule corresponds to one processing result. If this parameter is not specified, images will not be processed.

    Parameters of rules (a JSON array) are as follows:

    Parameter Type Required Description
    bucket String No Name of the destination bucket to store the results, formatted as BucketName-APPID. If this parameter is not specified, the results will be stored in the current bucket.
    fileid String Yes Path of the processing results. If the value of this parameter starts with a slash (/), the results will be stored in a specified folder. Otherwise, the results will be stored in the directory of the input image.
    rule String Yes Processing parameters. For more information, please see COS’s image processing API. To process an image using a specified style, the value must start with style/ with the style name followed. For example, if the style name is test, the value of rule should be style/test.

    Response

    Parameters in the response body are as follows:

    Parameter Type Description
    UploadResult Container Input image information

    Content of the UploadResult node:

    Parameter Type Description
    OriginalInfo Container Input image information
    ProcessResults Container Image processing results

    Content of the OriginalInfo node:

    Parameter Type Description
    Key String Name of the input image
    Location String Location of the image
    ImageInfo Container Input image information
    ETag String ETag of the input image. If the output image overwrites the input image, the value of ETag will be that of the output image.

    Content of the ImageInfo node:

    Parameter Type Description
    Format String Format
    Width Int Image width
    Height Int Image height
    Quality Int Image quality
    Ave String Average hue of an image
    Orientation Int Image rotation angle

    Content of the ProcessResults node:

    Parameter Type Description
    Object Container Processing result of each image

    Content of the Object node:

    Parameter Type Description
    Key String Filename
    Location String Location of the image
    Format String Image format
    Width Int Image width
    Height Int Image height
    Size Int Image size
    Quality Int Image quality
    ETag String ETag of the output image

    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:XXXXXXXXXXXX
    Pic-Operations: {"is_pic_info":1,"rules":[{"fileid":"test.jpg","rule":"imageView2/format/png"}]}
    Content-Length: 64
    [Object]
    

    Response

    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>
            </ImageInfo>
        </OriginalInfo>
        <ProcessResults>
            <Object>
                <Key>test.jpg</Key>
                <Location>examplebucket-1250000000.cos.ap-chengdu.myqcloud.com/test.jpg</Location>
                <Format>png</Format>
                <Width>640</Width>
                <Height>427</Height>
                <Size>463092</Size>
                <Quality>100</Quality>
                <ETag>&quot;eaa4e3d8fd498bbc63be3b71c46b9c61f23e3f0c&quot;</ETag>
            </Object>
        </ProcessResults>
    </UploadResult>
    
    Note:

    Processing upon upload supports the multipart upload feature of COS V5. You can process images by adding the Pic-Operations request header when calling the Complete Multipart Upload API.

    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:

    For more information, please see Complete Multipart Upload.

    Processing In-Cloud Data

    COS’s image processing API can process an in-cloud image and save the processing result to COS.

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

    Request content

    Pic-Operations is a JSON string. Its parameters are as follows:

    Parameter Type Required Description
    is_pic_info Int No Whether to return the input image information
    0 (default): no
    1: yes
    rules Array No Processing rules (up to 5 rules are supported). Each rule corresponds to one processing result. If this parameter is not specified, images will not be processed.

    Parameters of rules (a JSON array) are as follows:

    Parameter Type Required Description
    bucket String No Name of the destination bucket to store the results, formatted as BucketName-APPID. If this parameter is not specified, the results will be stored in the current bucket.
    fileid String Yes Path of the processing results. If the value of this parameter starts with a slash (/), the results will be stored in a specified folder. Otherwise, the results will be stored in the directory of the input image.
    rule String Yes Processing parameters. For more information, please see COS’s image processing API. To process an image using a specified style, the value must start with style/ with the style name followed. For example, if the style name is test, the value of rule should be style/test.

    Response

    Parameters in the response body are as follows:

    Parameter Type Description
    UploadResult Container Input image information

    Content of the UploadResult node:

    Parameter Type Description
    OriginalInfo Container Input image information
    ProcessResults Container Image processing results

    Content of the OriginalInfo node:

    Parameter Type Description
    Key String Name of the input image
    Location String Location of the image
    ImageInfo Container Input image information
    ETag String ETag of the input image. If the output image overwrites the input image, the value of ETag will be that of the output image.

    Content of the ImageInfo node:

    Parameter Type Description
    Format String Format
    Width Int Image width
    Height Int Image height
    Quality Int Image quality
    Ave String Average hue of an image
    Orientation Int Image rotation angle

    Content of the ProcessResults node:

    Parameter Type Description
    Object Container Processing result of each image

    Content of the Object node:

    Parameter Type Description
    Key String Filename
    Location String Location of the image
    Format String Image format
    Width Int Image width
    Height Int Image height
    Size Int Image size
    Quality Int Image quality
    ETag String ETag of the output image

    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: XXXXXXXXXX
    Pic-Operations: {"is_pic_info":1,"rules":[{"fileid":"test.jpg","rule":"imageView2/format/png"}]}
    Content-Length: XX
    

    Response

    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>
            </ImageInfo>
        </OriginalInfo>
        <ProcessResults>
            <Object>
                <Key>test.jpg</Key>
                <Location>examplebucket-1250000000.cos.ap-chengdu.myqcloud.com/test.jpg</Location>
                <Format>png</Format>
                <Width>640</Width>
                <Height>427</Height>
                <Size>463092</Size>
                <Quality>100</Quality>
                <ETag>&quot;eaa4e3d8fd498bbc63be3b71c46b9c61f23e3f0c&quot;</ETag>
            </Object>
        </ProcessResults>
    </UploadResult>