Skip to content

Lossless Image Compression โ€‹

Updated

Re-encode an image to cut its file size substantially while keeping it visually lossless. The only thing you need to set is ImageTask.EncodeConfig.ImageEncodeConfig:

  • Output format Format (e.g. AVIF)
  • Relative quality Quality (relative to the source image, 1โ€“100)

Optionally add TransformConfig.ImageResize to resize and compress in a single request. In our tests, two large images shrank by 76%โ€“78% (see Reference Results).

What "lossless" means here

"Lossless" here means visually lossless: after re-encoding, the difference in quality is not visible to the eye. It is not bit-exact mathematical lossless compression. The compression ratio depends on both Format and Quality โ€” before going live, compare results side by side on your own assets, as in Reference Results.

Example conventions in this doc

All examples use COS input + COS output. To use URL / AWS-S3 / VOD or other input and output types, replace only InputInfo and OutputStorage; the ImageTask section stays the same.

API Documentation โ€‹

PurposeAPIOfficial docsAPI Explorer
Start image processingProcessImageProcessImageTry it online
Query task statusDescribeImageTaskDetailDescribeImageTaskDetailTry it online

For the full definition of the encoding parameters, see ImageEncodeConfig in the official data structure reference.

Request Structure โ€‹

COS input + COS output, resized to 1280ร—720 and re-encoded as AVIF at quality 50:

json
{
  "InputInfo": {
    "Type": "COS",
    "CosInputInfo": {
      "Bucket": "your-bucket-1250000000",
      "Region": "ap-shanghai",
      "Object": "image/lenna.png"
    }
  },
  "OutputStorage": {
    "Type": "COS",
    "CosOutputStorage": {
      "Bucket": "your-bucket-1250000000",
      "Region": "ap-shanghai"
    }
  },
  "OutputDir": "/share/output/",
  "ImageTask": {
    "TransformConfig": {
      "ImageResize": {
        "Width": 1280,
        "Height": 720
      }
    },
    "EncodeConfig": {
      "ImageEncodeConfig": {
        "Format": "AVIF",
        "Quality": 50
      }
    }
  }
}

ImageEncodeConfig (encoding / compression, core) โ€‹

Path: ImageTask.EncodeConfig.ImageEncodeConfig

ParameterDescriptionValues
FormatOutput image formatDefaults to the source format; animation is not supported. The examples in this doc use AVIF. The official structure reference lists JPEG / PNG / BMP / WebP
QualityRelative quality of the image1โ€“100, relative to the source image quality; defaults to the source quality. Lower values give smaller files

Start from the sample values

Format=AVIF + Quality=50 are the parameters behind the measured results in this doc and make a good starting point. For quality-sensitive content (e.g. product detail shots), raise Quality and weigh file size against visual quality.

ImageResize (resizing, optional) โ€‹

Path: ImageTask.TransformConfig.ImageResize. If you only want to compress without changing dimensions, omit TransformConfig entirely.

ParameterDescriptionValues
SwitchCapability switchON: enabled (default); OFF: disabled
ModeResize modepercent (default): scale by a ratio; mfit: scale to the larger rectangle of the given width and height; lfit: scale to the smaller rectangle; fill: scale to the larger rectangle, then center-crop to the given size; pad: scale to the smaller rectangle, then pad to the given size; fixed: force-scale to the exact width and height
PercentScale ratioUsed when Mode=percent; decimals allowed, range [0.1, 10.0], default 1.0
Width / HeightTarget width / heightRange [1, 16384]; take precedence when Mode is not percent
LongSide / ShortSideTarget long side / short sideRange [1, 16384]; used when Mode is not percent and neither Width nor Height is set

Input and Output Location โ€‹

ParameterDescription
InputInfoThe image to compress. The examples use COS (Bucket / Region / Object)
OutputStorageTarget storage for the output, at the same level as ImageTask. If omitted, it inherits the storage location from InputInfo
OutputDirOutput directory, e.g. /share/output/; the output keeps the source file name inside that directory. If omitted, it is the same directory as the input file

Business Examples โ€‹

Compress Only, Keep Dimensions โ€‹

Omit TransformConfig to keep the original resolution and only re-encode:

json
{
  "InputInfo": {
    "Type": "COS",
    "CosInputInfo": {
      "Bucket": "your-bucket-1250000000",
      "Region": "ap-shanghai",
      "Object": "image/lenna.png"
    }
  },
  "OutputDir": "/share/output/",
  "ImageTask": {
    "EncodeConfig": {
      "ImageEncodeConfig": { "Format": "AVIF", "Quality": 50 }
    }
  }
}

This example omits OutputStorage, so the output inherits the COS bucket and region of the input.

Resize + Compress โ€‹

This is the full example in Request Structure above: resize the image to 1280ร—720 first, then encode it as AVIF at quality 50.

Querying Results (DescribeImageTaskDetail) โ€‹

Once ProcessImage returns a TaskId, poll the task status with DescribeImageTaskDetail.

Request:

json
{ "TaskId": "260000****-WorkflowTask-*************" }

Response โ€” Success โ€‹

json
{
  "Response": {
    "CreateTime": "2025-05-21T01:02:51Z",
    "FinishTime": "2025-05-21T01:02:52Z",
    "ImageProcessTaskResultSet": [
      {
        "Output": {
          "OutputStorage": {
            "CosOutputStorage": {
              "Bucket": "your-bucket-1250000000",
              "Region": "ap-shanghai"
            },
            "Type": "COS"
          },
          "Path": "/share/output/test_2.jpeg"
        }
      }
    ],
    "RequestId": "bf13665d-843a-45f2-a297-97e9ef26966a",
    "Status": "FINISH",
    "TaskType": "WorkflowTask"
  }
}
FieldDescription
StatusTask status; FINISH means the task has reached a terminal state
ImageProcessTaskResultSet[].Output.PathPath of the compressed image in the output storage
ImageProcessTaskResultSet[].Output.OutputStorageStorage holding the output (type / bucket / region)
CreateTime / FinishTimeTask creation and completion time (UTC)

The sample response only illustrates the structure

The response above comes from a real task, but its output file name test_2.jpeg is not from the same call as the request example in this doc. In practice the output file name inherits the input file name, and the extension follows Format.

Reference Results โ€‹

The table below shows measured results on two large images. Open a comparison link to drag and compare online โ€” left / right are the original / compressed image.

ImageOriginal size (MB)Compressed size (MB)Size reductionComparison
Image A (2752ร—1536)4.541.0776.3%Side by side
Image B (550ร—3072)16.473.5978.2%Side by side

"Size reduction" = 1 โˆ’ compressed size รท original size. The percentages come from the original test data; recomputing from the two-decimal MB values in the table gives 76.4% for Image A, a difference caused by rounding the sizes. Compression depends heavily on image content, so treat the table as reference values and measure on your own assets.

DocumentDescription
API ReferenceGeneral MPS authentication, TC3 signing, and request execution conventions
SDK ReferenceThe full flow for calling key MPS APIs with the official SDKs

Built with VitePress ยท Deployed on Tencent EdgeOne Pages