All Products
Search
Document Center

Object Storage Service:IMG

Last Updated:Nov 06, 2024

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

Usage of IMG

You can use standard HTTP GET requests to access IMG. You can configure IMG parameters in the query string 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

    Private, public-read, or public-read-write

    Public-read or public-read-write

    You can anonymously access a processed image by using a subdomain in the following format:

    http://<yourBucketName>.<yourEndpoint>/<yourObjectName>?x-oss-process=image/<yourAction>,<yourParamValue>

    Parameter

    Description

    yourBucketName

    The name of the bucket.

    yourEndpoint

    The endpoint of the region in which the bucket is located.

    yourObjectName

    The name of the image object.

    image

    The identifier reserved by IMG.

    yourAction

    The operations that are performed on the image, such as resizing, cropping, and rotating.

    yourParamValue

    The parameters of 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 subdomain in the following format:

      http://<yourBucketName>.<yourEndpoint>/<yourObjectName>?x-oss-process=style/<yourStyleName>
      • style: the identifier reserved by IMG for the custom image style.

      • yourStyleName: the name of the custom image style. The name is specified by the Rule Name parameter when you create the custom image 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 over HTTPS

      IMG supports access over HTTPS. Example:

      https://image-demo.oss-cn-hangzhou.aliyuncs.com/example.jpg?x-oss-process=image/resize,w_100
  • Authorize 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

    Private, public-read, or public-read-write

    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({
      // 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: "oss-cn-hangzhou",
      // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
      accessKeyId: process.env.OSS_ACCESS_KEY_ID,
      accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
      authorizationV4: true,
      // Specify the name of the bucket. 
      bucket: "examplebucket",
    });
    // Set the validity period of the URL to 10 minutes and the image style to image/resize,w_300. 
    const signUrl = client.signatureUrl("example.png", {
      expires: 600,
      process: "image/resize,w_300",
    });
    console.log("signUrl=" + signUrl);
    Note
    • Authorized access supports custom image styles, HTTPS, and cascade processing.

    • The validity period (expires) is measured in seconds.

  • Access an image by using OSS SDKs

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

    OSS SDKs allow 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 object:

      const OSS = require('ali-oss');
      
      const client = new OSS({
        // 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: 'yourregion',
        // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
        accessKeyId: process.env.OSS_ACCESS_KEY_ID,
        accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
        authorizationV4: true,
        // Specify the name of the bucket. 
        bucket: 'yourbucketname'
      });
      
      // Resize the image to 100 × 100 pixels. 
      async function scale() {
        try {
          const result = await client.get('example.jpg', './example-resize.jpg', { process: 'image/resize,m_fixed,w_100,h_100'});
        } catch (e) {
          console.log(e);
        }
      }
      
      scale()
      
      // Crop the image to 100 × 100 pixels starting from the position specified by coordinate pair (100, 100). 
      async function cut() {
        try {
           const 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)
        }
      }
      
      cut()
      
      // Rotate the image 90 degrees. 
      async function rotate() {
        try {
          const result = await client.get('example.jpg', './example-rotate.jpg', { process: 'image/rotate,90'});
        } catch (e) {
          console.log(e);
        }
      }
      
      rotate()
      
      // Sharpen the image. Set the parameter to 100. 
      async function sharpen() {
        try {
          const result = await client.get('example.jpg', './example-sharpen.jpg', { process: 'image/sharpen,100'});
        } catch (e) {
          console.log(e);
        }
      }
      
      sharpen()
      
      // Add watermarks to the image. 
      async function watermark() {
        try {
          const result = await client.get('example.jpg', './example-watermark.jpg', { process: 'image/watermark,text_SGVsbG8g5Zu-54mH5pyN5YqhIQ'});
        } catch (e) {
          console.log(e);
        }
      }
      
      watermark()
      
      // Convert the format of the image. 
      async function format() {
        try {
          const result = await client.get('example.jpg', './example-format.jpg', { process: 'image/format,png'});
        } catch (e) {
          console.log(e);
        }
      }
      
      format()
      
      // Obtain the image information. 
      async function info() {
        try {
          const result = await client.get('example.jpg', './example-info.txt', {process: 'image/info'});
        } catch (e) {
          console.log(e);
        }
      }
      
      info()
    • Custom image styles

      Note

      You must log on to the OSS console to create a custom image style named 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({
        // 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: 'yourregion',
        // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
        accessKeyId: process.env.OSS_ACCESS_KEY_ID,
        accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
        authorizationV4: true,
        // Specify the name of the bucket. 
        bucket: 'yourbucketname'
      });
      
      // Resize the image to 100 × 100 pixels. 
      async function scale() {
        try {
          const result = await client.get('example.jpg', './example-resize.jpg', { process: 'image/resize,m_fixed,w_100,h_100'});
        } catch (e) {
          console.log(e);
        }
      }
      
      scale()
      
      // Crop the image to 100 x 100 pixels starting from the position specified by the coordinate pair (100, 100). 
      async function cut() {
        try {
           const 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)
        }
      }
      
      cut()
      
      // Rotate the image 90 degrees. 
      async function rotate() {
        try {
          const result = await client.get('example.jpg', './example-rotate.jpg', { process: 'image/rotate,90'});
        } catch (e) {
          console.log(e);
        }
      }
      
      rotate()
      
      // Sharpen the image. Set the parameter to 100. 
      async function sharpen() {
        try {
          const result = await client.get('example.jpg', './example-sharpen.jpg', { process: 'image/sharpen,100'});
        } catch (e) {
          console.log(e);
        }
      }
      
      sharpen()
      
      // Add watermarks to the image. 
      async function watermark() {
        try {
          const result = await client.get('example.jpg', './example-watermark.jpg', { process: 'image/watermark,text_SGVsbG8g5Zu-54mH5pyN5YqhIQ'});
        } catch (e) {
          console.log(e);
        }
      }
      
      watermark()
      
      // Convert the format of the image. 
      async function format() {
        try {
          const result = await client.get('example.jpg', './example-format.jpg', { process: 'image/format,png'});
        } catch (e) {
          console.log(e);
        }
      }
      
      format()
      
      // Obtain the image information. 
      async function info() {
        try {
          const result = await client.get('example.jpg', './example-info.txt', {process: 'image/info'});
        } catch (e) {
          console.log(e);
        }
      }
      
      info()
    • 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({
        // 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: 'yourregion',
        // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
        accessKeyId: process.env.OSS_ACCESS_KEY_ID,
        accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
        authorizationV4: true,
        // Specify the name of the bucket. 
        bucket: 'yourbucketname'
      });
      
      // Perform cascade processing.
      async function cascade () {
        try {
          const 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({
  // 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: 'yourregion',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the bucket. 
  bucket: 'yourbucketname'
});

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 and configure the destination bucket that is used to save the processed image. 
processImage("image/resize,m_fixed,w_100,h_100", "target bucket")

// Crop the image and configure the destination bucket that is used to save the processed image. 
processImage("image/crop,w_100,h_100,x_100,y_100,r_1", "target bucket")

// Rotate the image and configure the destination bucket that is used to save the processed image. 
processImage("image/rotate,90", "target bucket")

// Sharpen the image and configure the destination bucket that is used to save the processed image. 
processImage("image/sharpen,100", "target bucket")

// Add watermarks to the image and configure the destination bucket that is used to save the processed image. 
processImage("image/watermark,text_SGVsbG8g5Zu-54mH5pyN5YqhIQ", "target bucket")

// 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")

// 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")

References

  • For more information about the supported IMG parameters, see IMG parameters.

  • For the complete sample code that is used to perform IMG operations, visit GitHub.