Docs

Torch Object Storage

Image processing

Overview

TOS allows you to process image files stored in TOS. You can initiate image processing by including the appropriate parameters in requests made through the GetObject API. Supported features include resizing, cropping, watermarking, and format conversion.

Billing notes

You will incur fees for image processing operations, request charges, and data transfer costs when using the image processing feature. For pricing details, see Data processing, Requests and Data transfer.

Data retrieval fees will apply when processing images stored in Infrequent Access Storage or Flashback Archive. These fees are calculated based on the size of the original image before processing. For more information, see Data retrievals.

Constraints and limitations

Category	Description
Format	The original image must be in the JPG, JPEG, PNG, BMP, GIF, WebP, or TIFF format. tip Some image processing operations may have exceptions regarding supported image formats. The documentation for each operation details these exceptions.
Size	The original image size must be 20 MB or smaller. The original image can have a width and height of up to 30,000 pixels, for a total of up to 250 million pixels. However, the width and height cannot exceed 4,096 pixels for the rotate operation. TOS will not process WebP images that exceed 16,383 pixels in width or height. Any image processing features applied to such images will leave them unchanged. The resized image can have a width and height of up to 16,384 pixels, for a total of 16,777,216 pixels.
QPS	The QPS limit for processing images in each region is 50. tip If you have a compute-intensive workload or usage that exceeds these limits, submit a ticket to consult with our technical team or your designated account manager.
Concurrency	The default concurrency limits for processing images are as follows: China (Beijing): 20 Other regions: 10 tip If you have a compute-intensive workload or usage that exceeds these limits, submit a ticket to consult with our technical team or your designated account manager.
Server-side encryption	You can use TOS to process images encrypted with SSE-TOS, SSE-C, or SSE-KMS, but there are some limitations to consider: SSE-C When processing an image encrypted with SSE-C, you must include the following SSE-C request headers: x-tos-server-side-encryption-customer-algorithm, x-tos-server-side-encryption-customer-key, and x-tos-server-side-encryption-customer-key-MD5. For more information on SSE-C headers, see Using server-side encryption with customer-provided keys (SSE-C). You can add a watermark to an image encrypted with SSE-C. However, you cannot use an SSE-C-encrypted image as a watermark on another image. For example, if images aaa and bbb are encrypted with SSE-C but image ccc is not, then you can add ccc as a watermark to bbb. However, you cannot add image aaa as a watermark to image bbb. SSE-KMS You cannot process images encrypted with SSE-KMS via anonymous access. To process SSE-KMS-encrypted images, you must activate Key Management Service (KMS) and have permission to access the master key. Requests must also be signed using valid credentials. You can use pre-signed URLs, APIs, or SDKs for this purpose. For details on using APIs and SDKs for image processing, see the Using REST APIs section below and Basic Image Processing (Java SDK). By default, processed images and video frames use the server-side encryption method of the bucket to which they are saved. If the target bucket uses SSE-KMS, ensure your account has permission for the bucket's KMS key. Otherwise, you will not be able to save the processed images and video frames.
Mirroring	The mirroring feature does not work with the image processing feature.

Image processing methods

You can process images stored in TOS buckets using REST APIs or file URLs. This allows you to easily resize, crop, and watermark images, as well as quickly retrieve processed images at any time.

tip

Processed images are returned immediately and are not saved in your bucket.

Using REST APIs

Example:

GET /example.jpg?x-tos-process=image/resize,w_300 HTTP/1.1
Host: endpoint
X-Tos-Content-Sha256: sha256
X-Tos-Date: 20220827T132948Z
Authorization: authorization

Using file URLs

Example:

http://bucket.endpoint/example.jpg?x-tos-process=image/resize,w_300

tip

To process a private image, use a SDK to generate a pre-signed URL that includes the image processing parameters. For how to generate pre-signed URLs in various programming languages, see the following documents:

Generating a pre-signed URL for image processing

Generating a pre-signed URL for image transcoding/frame extraction

Image processing features

The following table lists image processing features supported by TOS. Each feature corresponds to a parameter. If you specify multiple parameters in a request, TOS will process the image in the order of the parameters.

tip

Unless otherwise specified, only positive integers are supported for parameters related to image pixels. Please refer to the description of each parameter to see what values are allowed

Feature	Parameter	Description
Resize	resize	Resizes an image to specific dimensions.
Watermark	watermark	Adds a text or image watermark to an image.
Crop	crop	Crops an image into a rectangle of a specified size.
Quality	quality	Adjusts the quality of a JPG, JPEG or WebP image.
Format	format	Converts the format of an image.
Info	info	Returns image information, including basic data and EXIF data.
Auto-orient	auto-orient	Automatically rotates an image based on its orientation parameters.
Circle	circle	Crops an image into a circle of a specified radius based on its center point.
Indexcrop	indexcrop	Splits an image into segments along the x- or y-axis and selects one of the segments.
Rounded-corners	rounded-corners	Uses the specified radius to crop an image into a rounded rectangle.
Blur	blur	Blurs an image.
Rotate	rotate	Rotates an image clockwise by a specified degree.
Interlace	interlace	Converts a JPG or JPEG image to a progressive display format.
Average-hue	average-hue	Gets the average color of an image.
Bright	bright	Adjusts the brightness of an image.
Sharpen	sharpen	Sharpens an image.
Contrast	contrast	Adjusts the contrast of an image.
HEIF	format	Converts an image to the High-Efficiency Image File (HEIF) format.
Save	save	Saves a processed image to a specified bucket.
Inspection	inspect	Detects whether an image contains non-image content, such as MPEG-TS.
Strip	strip	Removes metadata such as EXIF, gAMA, and iCCP from an image.

Last updated: 2026.02.04 17:11:22