Image Processing (IMG) is an image processing service that is provided by Object Storage Service (OSS). The service is secure, cost-effective, and highly reliable and can be used to process large numbers of images. After you upload source images to OSS, you can call RESTful API operations to process the images on a device that is connected over the Internet anytime, anywhere.

For more information about IMG parameters, see IMG parameters.

Usage of image processing

You can use standard HTTP GET requests to access IMG. You can configure IMG parameters in QueryString of a URL.

If the access control list (ACL) of an image object is private, only authorized users can access the image.

  • Anonymous access

    If the ACL of an image object is public-read, as described in the following table, anonymous users can access the image object.

    Bucket ACL Object ACL
    public-read or public-read-write Default
    Any ACL public-read or public-read-write

    You can anonymously access a processed image by using a third-level domain in the following format:

    http://<yourBucketName>.<yourEndpoint>/<yourObjectName>?x-oss-process=image/<yourAction>,<yourParamValue>
    Parameter Description
    bucket The name of the bucket.
    endpoint The endpoint that is used to access the region in which the bucket is located.
    object The name of the image object.
    image The identifier reserved by IMG.
    action The operations that are performed on the image such as resizing, cropping, and rotating.
    param The parameters that correspond to the operations that are performed on the image.
    • Basic operations

      For example, you can resize an image to a width of 100 pixels and adjust the height based on the ratio by using the following URL:

      http://image-demo.oss-cn-hangzhou.aliyuncs.com/example.jpg?x-oss-process=image/resize,w_100
    • Custom image styles

      You can anonymously access IMG by using a third-level domain in the following format:

      http://<yourBucketName>.<yourEndpoint>/<yourObjectName>?x-oss-process=style/<yourStyleName>
      • style: the identifier reserved by IMG for the custom style.
      • yourStyleName: the name of the custom style. The name is specified by the Rule Name parameter when you create the custom style in the OSS console.

      Example:

      http://image-demo.oss-cn-hangzhou.aliyuncs.com/example.jpg?x-oss-process=style/oss-pic-style-w-100
    • Cascade processing

      You can use cascade processing to perform multiple operations in sequence on an image by using a URL in the following format:

      http://<yourBucketName>.<yourEndpoint>/<yourObjectName>?x-oss-process=image/<yourAction1>,<yourParamValue1>/<yourAction2>,<yourParamValue2>/...

      Example:

      http://image-demo.oss-cn-hangzhou.aliyuncs.com/example.jpg?x-oss-process=image/resize,w_100/rotate,90
    • Access by using HTTPS

      IMG supports access by using HTTPS. Example:

      https://image-demo.oss-cn-hangzhou.aliyuncs.com/example.jpg?x-oss-process=image/resize,w_100
  • Authorized access

    If the ACL of an image object is private, you must have permissions on the image object before you can perform operations on the image object.

    Bucket ACL Object ACL
    Private Default
    Any ACL Private

    The following code provides an example on how to generate a signed URL for IMG:

    const OSS = require('ali-oss');
    
    const client = new OSS({
      bucket: '<Your BucketName>',
      // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
      region: '<Your Region>',
      // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
      accessKeyId: '<Your AccessKeyId>',
      accessKeySecret: '<Your AccessKeySecret>',
    });
    // Set the validity period to 10 minutes. The image processing style is "image/resize,w_300".
    let signUrl = client.signatureUrl('example.jpg', {expires: 600, 'process' : 'image/resize,w_300'});
    console.log("signUrl="+signUrl);
    Note
    • Authorized access supports custom styles, HTTPS, and cascade processing.
    • The validity period (expires) is measured in seconds.
  • Access by using OSS SDKs

    You can use an OSS SDK to access and process an image object.

    The SDK allows you to specify custom image styles, access images over HTTPS, and perform cascade processing.

    • Basic operations

      The following code provides an example on how to perform basic operations on an image:

      const OSS = require('ali-oss');
      
      const client = new OSS({
        bucket: '<Your BucketName>',
        // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
        region: '<Your Region>',
        // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
        accessKeyId: '<Your AccessKeyId>',
        accessKeySecret: '<Your AccessKeySecret>',
      });
      // Resize the image.
      async function scale () {
        try {
          let result = await client.get('example.jpg', './example-resize.jpg', { process: 'image/resize,m_fixed,w_100,h_100'});
        } catch (e) {
          console.log(e);
        }
      }
      // Crop the image.
      async function cut () {
        try {
           let result = await client.get('example.jpg', './example-crop.jpg', { process: 'image/crop,w_100,h_100,x_100,y_100,r_1'});
        } catch (e) {
          console.log(e)
        }
      }
      // Rotate the image.
      async function rotate () {
        try {
          let result = await client.get('example.jpg', './example-rotate.jpg', { process: 'image/rotate,90'});
        } catch (e) {
          console.log(e);
        }
      }
      // Sharpen the image.
      async function sharpen () {
        try {
          let result = yield client.get('example.jpg', './example-sharpen.jpg', { process: 'image/sharpen,100'});
        } catch (e) {
          console.log(e);
        }
      }
      // Add watermarks to the image.
      async function watermark () {
        try {
          let result = yield client.get('example.jpg', './example-watermark.jpg', { process: 'image/watermark,text_SGVsbG8g5Zu-54mH5pyN5YqhIQ'});
        } catch (e) {
          console.log(e);
        }
      }
      // Convert the format of the image.
      async function format () {
        try {
          let result = await client.get('example.jpg', './example-format.jpg', { process: 'image/format,png'});
        } catch (e) {
          console.log(e);
        }
      }
      // Obtain information about the image.
      async function info () {
        try {
          let result = await client.get('example.jpg', './example-info.txt', {process: 'image/info'});
        } catch (e) {
          console.log(e);
        }
      }
    • Custom image styles
      Note You must first log on to the OSS console to create the custom style "example-style".

      The following code provides an example on how to specify a custom image style:

      const OSS = require('ali-oss');
      
      const client = new OSS({
        bucket: '<Your BucketName>',
        // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
        region: '<Your Region>',
        // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
        accessKeyId: '<Your AccessKeyId>',
        accessKeySecret: '<Your AccessKeySecret>',
      });
      // Specify the custom image style.
      async function style () {
        try {
          let result = await client.get('example.jpg', './example-custom-style.jpg', {process: 'style/example-style"'});
        } catch (e) {
          console.log(e);
        }
      }
      style();
    • Cascade processing

      The following code provides an example on how to perform cascade processing on an image:

      const OSS = require('ali-oss');
      
      const client = new OSS({
        bucket: '<Your BucketName>',
        // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
        region: '<Your Region>',
        // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
        accessKeyId: '<Your AccessKeyId>',
        accessKeySecret: '<Your AccessKeySecret>',
      });
      
      // Perform cascade processing.
      async function cascade () {
        try {
          let result = await client.get('example.jpg', './example-cascade.jpg', {process: 'image/resize,m_fixed,w_100,h_100/rotate,90'});
        } catch (e) {
          console.log(e);
        }
      }
      cascade();

Save processed images

The following code provides an example on how to save processed images:

const OSS = require('ali-oss');

const client = new OSS({
  bucket: '<Your BucketName>',
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
  region: '<Your Region>',
  // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>',
});

const sourceImage = 'sourceObject.png';
const targetImage = 'targetObject.jpg';
async function processImage(processStr, targetBucket) {
  const result = await client.processObjectSave(
    sourceImage,
    targetImage,
    processStr,
    targetBucket
  );
  console.log(result.res.status);
}

// Resize the image.
processImage("image/resize,m_fixed,w_100,h_100")

// Crop the image.
processImage("image/crop,w_100,h_100,x_100,y_100,r_1")

// Rotate the image.
processImage("image/rotate,90")

// Sharpen the image.
processImage("image/sharpen,100")

// Add watermarks to the image.
processImage("image/watermark,text_SGVsbG8g5Zu-54mH5pyN5YqhIQ")

// Convert the format of the image.
processImage("image/format,jpg")

// Convert the format of the image and configure the destination bucket that is used to save the processed image. 
processImage("image/format,jpg", "<target bucket>")