You can add Image Processing (IMG) parameters to GetObject requests to process image objects stored in Object Storage Service (OSS). For example, you can add image watermarks to images or convert image formats.

Parameters

OSS allows you to directly use one or more parameters to process images. You can also encapsulate multiple IMG parameters in a style to batch process images. For more information about image styles, see Image style.

When multiple IMG parameters are specified, OSS processes the image in the order of the parameters. The following table describes the parameters that you can configure to process images.

IMG operation Parameter Description
Resize images resize Resizes images to a specified size.
Incircle circle Crops images based on the center point of images to ellipses of the specified size.
Custom crop crop Crops rectangular images of the specified size.
Indexed cut indexcrop Cuts images along the specified horizontal or vertical axis and selects one of the images.
Rounded rectangle rounded-corners Crops images to rounded rectangles based on the specified rounded corner size.
Automatic rotation auto-orient Auto-rotates images for which the auto-orient parameter is configured.
Rotate rotate Rotates images clockwise based on the specified angle.
Blur blur Blurs images.
Brightness bright Adjusts the brightness of images.
Sharpen sharpen Sharpens images.
Contrast contrast Adjusts the contrast of images.
Gradual display interlace Configures gradual display for the JPG images.
Quality transformation quality Adjusts the quality of images in the JPG and WebP formats.
Format conversion format Converts image formats.
Add watermarks watermark Adds image or text watermarks to images.
Query the average tone average-hue Queries the average tone of images.
Query image information info Queries image information, including basic information and EXIF information.
For example, after you configure the resize and quality parameters for the example.jpg source image, the URL for an image named exmaple.jpg is https://image-demo.oss-cn-hangzhou.aliyuncs.com/example.jpg?x-oss-process=image/resize,w_300/quality,q_90. You can configure Content Delivery Network (CDN) back-to-origin rules to filter or retain the IMG parameters contained in the URLs of images that you want to retrieve. This way, you can retrieve source images or images processed by specifying IMG parameters from OSS.
  • Retrieve source images

    You can enable Parameter Filtering for CDN to remove all IMG parameters that follow the question mark (?) in the URL of the image you want to retrieve.In this case, the source image example.jpg is retrieved.

  • Retrieve processed images

    You can enable Retain Specified Parameters for CDN to retain all IMG parameters that follows the question mark (?) in the URL of the image you want to retrieve.In this case, the processed image is retrieved.

For more information about how to configure CDN back-to-origin rules, see Retain URL parameters.

Implementation methods

You can use object URLs, API operations, and SDKs to process images. For more information, see IMG implementation modes.

Usage notes

When you use IMG, take note of the following items:
  • Limits on source images
    • Only JPG, PNG, BMP, GIF, WebP, TIFF, and images are supported.
    • The size of the source image cannot exceed 20 MB.
    • For the rotate operation, the height or width of the source image cannot exceed 4,096 pixels. For other operations, the width or height of the source image cannot exceed 30,000 pixels, and the total pixel number of the source image cannot exceed 250 million.

      The pixel number of a dynamic image, such as a GIF image, is calculated by using the following formula: Width × Height × Number of image frames. The pixel number of a static image, such as a PNG image, is calculated by using the following formula: Width × Height.

  • Limits on resized images

    The width or height of the resized image cannot exceed 16,384 pixels. The total pixel number of the resized image cannot exceed 16,777,216 pixels.

  • Limits on image styles

    You can create up to 50 image styles for each bucket. To create more than 50 styles for a bucket, contact the technical support .

Billing

When you use IMG, you are charged the following fees:
  • Image processing fees

    You are charged for IMG based on the size of the source images only after the free quota is exceeded. For more information about image processing fees, see Data processing fees.

  • Request fees

    A GetObject request is generated each time when you use IMG to process an image. You are charged based on the number of generated requests. For more information about request fees, see API operation calling fees.

  • Traffic fees

    You are charged for the outbound traffic over the Internet based on the size of the source images. For more information about traffic fees, see Traffic fees.

Release notes

IMG provides two API versions: the later API version and the earlier API version. This topic describes the APIs of the later version. APIs of the earlier version are not updated. For more information about the compatibility between the later and earlier versions of APIs, see FAQ on using old and new versions of APIs and domain names.