How to process images using the Node.js SDK - Object Storage Service

Image processing is a secure, low-cost, and highly reliable service provided by OSS. After an image is uploaded to OSS, you can use simple RESTful interfaces to process it on any internet-connected device.

Image processing usage

Image processing uses standard HTTP GET requests. You can set the processing parameters in the URL query string.

If an image file is private, authorization is required for access.

Anonymous access

If an image file (object) has public-read access permissions, you can access the image service anonymously.

Bucket permissions	Object permissions
public-read or public-read-write	default
Any permissions	public-read or public-read-write

To anonymously access processed images, use a third-level domain in the following format:

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

Parameter	Description
yourBucketName	The bucket name.
yourEndpoint	The endpoint of the region where the bucket is located.
yourObjectName	The image file name.
image	The reserved flag for image processing.
yourAction	The operation to perform on the image, such as scaling, cropping, or rotating.
yourParamValue	The parameters for the operation.

Basic operations
For example, to scale an image to a width of 100 pixels and adjust the height proportionally:
```
http://image-demo.oss-cn-hangzhou.aliyuncs.com/example.jpg?x-oss-process=image/resize,w_100
```
Custom styles
You can access image processing anonymously using a third-level domain in the following format:
```
http://<yourBucketName>.<yourEndpoint>/<yourObjectName>?x-oss-process=style/<yourStyleName>
```
- style: The reserved flag for custom styles.
- yourStyleName: The name of the custom style. This is the rule name that you set in the console.
For example:
```
http://image-demo.oss-cn-hangzhou.aliyuncs.com/example.jpg?x-oss-process=style/oss-pic-style-w-100
```

Cascade processing

Cascade processing lets you perform multiple operations on an image in sequence. The format is as follows:

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

For example:

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

HTTPS access

The image service supports HTTPS access. For example:

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

Authorized access

For private files (objects), you must use authorization to access the image service.

Bucket permissions	Object permissions
private	default
Any permissions	private

The following code shows how to generate a signed URL for image processing:

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

const client = new OSS({
  // Set region to the region where the bucket is located. For example, for China (Hangzhou), set region to oss-cn-hangzhou.
  region: "oss-cn-hangzhou",
  // Obtain access credentials from environment variables. Before running this sample code, make sure the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Set bucket to your bucket name.
  bucket: "examplebucket",
});
// The expiration time is 10 minutes. The image processing style is "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 styles, HTTPS, and cascade processing.
The expires parameter is specified in seconds.

SDK access

You can use the software development kit (SDK) to directly access and process image files regardless of their permissions.

The SDK supports custom styles, HTTPS, and cascade processing for image files.

Basic operations

The following code shows how to perform basic image processing operations:

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

const client = new OSS({
  // Set region to the region where the bucket is located. For example, for China (Hangzhou), set region to oss-cn-hangzhou.
  region: 'yourregion',
  // Obtain access credentials from environment variables. Before running this sample code, make sure the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Set bucket to your bucket name.
  bucket: 'yourbucketname'
});

// Scale the image to a fixed width and height of 100 px.
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 a width and height of 100 px, starting from the coordinate (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 with a sharpening parameter of 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 a watermark to the image.
async function watermark() {
  try {
    const result = await client.get('example.jpg', './example-watermark.jpg', { process: 'image/watermark,text_SGVsbG8gQWxpYmFiYSBDbG91ZCE='});
  } catch (e) {
    console.log(e);
  }
}

watermark()

// Convert the image format.
async function format() {
  try {
    const result = await client.get('example.jpg', './example-format.jpg', { process: 'image/format,png'});
  } catch (e) {
    console.log(e);
  }
}

format()

// Get 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 styles

Note

You must first add the custom style 'example-style' in the OSS console.

The following code shows how to use a custom style for an image:

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

const client = new OSS({
  // Set yourregion to the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set Region to oss-cn-hangzhou.
  region: 'yourregion',
  // Obtain access credentials from environment variables. Before you run this code sample, 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,
  // Set yourbucketname to the bucket name.
  bucket: 'yourbucketname'
});

// Scale the image to a fixed width and height of 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 a width and height of 100 pixels, starting from the coordinate (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. The sharpening parameter is 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 a watermark 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 image format.
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 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 shows how to perform cascade processing on an image:

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

const client = new OSS({
  // Set region to the region where the bucket is located. For example, for China (Hangzhou), set region to oss-cn-hangzhou.
  region: 'yourregion',
  // Obtain access credentials from environment variables. Before running this sample code, make sure the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Set bucket to your bucket name.
  bucket: 'yourbucketname'
});

// 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();

Image processing persistence

The following code shows how to save the results of image processing:

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

const client = new OSS({
  // Set region to the region where the bucket is located. For example, for China (Hangzhou), set region to oss-cn-hangzhou.
  region: 'yourregion',
  // Obtain access credentials from environment variables. Before running this sample code, make sure the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Set bucket to your bucket name.
  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);
}

// Save the processing result: Scale the image and set the target bucket to save the result.
processImage("image/resize,m_fixed,w_100,h_100", "target bucket")

// Save the processing result: Crop the image and set the target bucket to save the result.
processImage("image/crop,w_100,h_100,x_100,y_100,r_1", "target bucket")

// Save the processing result: Rotate the image and set the target bucket to save the result.
processImage("image/rotate,90", "target bucket")

// Save the processing result: Sharpen the image and set the target bucket to save the result.
processImage("image/sharpen,100", "target bucket")

// Save the processing result: Add a watermark to the image and set the target bucket to save the result.
processImage("image/watermark,text_SGVsbG8gQWxpYmFiYSBDbG91ZCE=", "target bucket")

// Save the processing result: Convert the image format and set the target bucket to save the result.
processImage("image/format,jpg", "target bucket")

References

For more information about the parameters for image processing, see Image processing.
For complete sample code for image processing, see the GitHub examples.