Image Processing (IMG) provided by OSS is a secure, cost-effective, and highly reliable image processing service that processes large amounts of data. After you upload source images to OSS, you can call RESTful API operations to process the images anytime, anywhere, and on any Internet device.

For more information about IMG, see Image Processing.

Basic features

OSS offers the following IMG features:

Usage of image processing

IMG uses the standard HTTP GET request for access. You can configure image processing parameters in the QueryString of a URL.

If the ACL of an image object is Private, only authorized users are allowed to access the image.

  • Anonymous access

    If the ACL of an image object is public-read 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

    Access image processing anonymously using the 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 domain name to access the region in which the bucket is located
    object The image object uploaded to the OSS
    image The identifier reserved by the image processing
    action Operations on images, such as scaling, cropping, and rotating
    param The parameter corresponding to the operations on the image
    • Basic operations

      For example, scale an image to a width of 100 and adjust the height based on the ratio:

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

      Access image processing anonymously using the third-level domain in the following format:

      http://<yourBucketName>.<yourEndpoint>/<yourObjectName>?x-oss-process=style/<yourStyleName>
      • style: the identifier reserved by the system for the custom style
      • yourStyleName: the name of the custom style, that is, the rule name of the console-defined style

      Example:

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

      You can use cascading 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 through HTTPS

      IMG also supports access over 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 an image processing URL with signature:

    const OSS = require('ali-oss');
    
    const client = new OSS({
      bucket: '<Your BucketName>',
      // The endpoint of the China (Hangzhou) region is used in this example. Specify the actual endpoint.
      region: '<Your Region>',
      // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. 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 cascading processing.
    • The validity period (expires) is measured in seconds.
  • Access by using SDK

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

    The SDK allows you to access an image through HTTPS, customize the image style, and perform cascading 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>',
        // The endpoint of the China (Hangzhou) region is used in this example. Specify the actual endpoint.
        region: '<Your Region>',
        // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to the RAM console.
        accessKeyId: '<Your AccessKeyId>',
        accessKeySecret: '<Your AccessKeySecret>',
      });
      // Scale 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.
      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 image format.
      async function format () {
        try {
          let result = await client.get('example.jpg', './example-format.jpg', { process: 'image/format,png'});
        } catch (e) {
          console.log(e);
        }
      }
      // Obtain the image information.
      async function info () {
        try {
          let result = await client.get('example.jpg', './example-info.txt', {process: 'image/info'});
        } catch (e) {
          console.log(e);
        }
      }
    • Custom styles
      Note You must first log on to the OSS console to create custom style "example-style".

      The following code provides an example on how to customize an image style:

      const OSS = require('ali-oss');
      
      const client = new OSS({
        bucket: '<Your BucketName>',
        // The endpoint of the China (Hangzhou) region is used in this example. Specify the actual endpoint.
        region: '<Your Region>',
        // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to the RAM console.
        accessKeyId: '<Your AccessKeyId>',
        accessKeySecret: '<Your AccessKeySecret>',
      });
      // Custom styles
      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();
    • Cascading processing

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

      const OSS = require('ali-oss');
      
      const client = new OSS({
        bucket: '<Your BucketName>',
        // The endpoint of the China (Hangzhou) region is used in this example. Specify the actual endpoint.
        region: '<Your Region>',
        // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to the RAM console.
        accessKeyId: '<Your AccessKeyId>',
        accessKeySecret: '<Your AccessKeySecret>',
      });
      
      // Cascading 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();

Image processing persistence

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

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

const client = new OSS({
  bucket: '<Your BucketName>',
  // The endpoint of the China (Hangzhou) region is used in this example. Specify the actual endpoint.
  region: '<Your Region>',
  // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. 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);
}

// Scale 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.
processImage("image/watermark,text_SGVsbG8g5Zu-54mH5pyN5YqhIQ")

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

// Convert the image format and configure the target bucket to save processed images.
processImage("image/format,jpg", "<target bucket>")