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);
NoteAuthorized 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
NoteYou 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.