Image Compression API

Try on PicWish

Compress images through the API by quality, target file size, or output dimensions. It supports image URLs and local file uploads for batch compression, ecommerce image optimization, and website asset optimization, with async and sync request modes.

The result image URL is valid for 1 hour. Please download and store it promptly.

Authentication

Every API request must include your API Key in the X-API-KEY request header. Send it with each request exactly as shown in the examples and parameter descriptions.

X-API-KEY: YOUR_API_KEY

Create an image compression task

POST /api/tasks/visual/imgcompress

Body Parameters

image_url string optional

Source image URL. If this parameter is present, the other image source parameter must be empty.

one required

image_file file optional

Source image file as binary data. If this parameter is present, the other image source parameter must be empty.

For image upload requirements, see Guidelines and Limits #7.

sync integer optional

Whether to wait for and return the result immediately. Results are kept for up to 1 hour.

0: Return a task_id asynchronously and fetch the result later with task_id;
1: Wait for and return the result synchronously.

format string optional

Output format. For jpg, png, or webp source images, the original format is used by default. Otherwise, the service recommends an output format.

jpg: Return a JPG image;
png: Return a PNG image;
webp: Return a WebP image.

return_type integer optional

Result return format. Default: 1.

1: Return an image URL;
2: Return a Base64-encoded string.

quality integer optional

Compression quality. Range: 1–100. If this parameter is present, kbyte must be empty.

one optional

kbyte integer optional

Target compressed image size in KB. Range: 0–51200. If this parameter is present, quality must be empty. PNG output does not support target-size compression.

width integer optional

Output image width. Range: 0–8000. If height is empty, the height is calculated proportionally.

height integer optional

Output image height. Range: 0–8000. If width is empty, the width is calculated proportionally.

Return Parameters

status number

HTTP response status code. See Status Code Definitions.

200: Request succeeded;
Non-200: Request failed.

message string

API response message. Usually success for a successful request.

data.task_id string

Async image compression task ID. Returned after the task is created, and used to query the compression result later.

status number

HTTP response status code. See Status Code Definitions.

200: Request succeeded;
Non-200: Request failed.

message string

API response message. Usually success for a successful request.

data.task_id string

Image compression task ID.

data.created_at string

Timestamp of task creation.

data.processed_at string

Timestamp when the task started to be processed.

data.completed_at string

Timestamp of task completion.

data.image string

Compressed result image URL or base64 data. The URL is valid for 1 hour.

data.progress number

Task progress.

100: Processing is complete.

data.state number

Task status code. See Status Code Definitions.

1: Succeeded;
> 1: Processing;
< 0: Failed;
-7: Invalid image file.

Query image compression result

For asynchronous requests, poll the result once every 1 second. The maximum polling duration for this API is 120 seconds; if the total polling time exceeds this without a result, treat it as a timeout failure.

GET /api/tasks/visual/imgcompress/{task_id}

Path Parameters

task_id string required

Image compression task ID returned after creating an async task. Use it to query the processing result.

Return Parameters

status number

HTTP response status code. See Status Code Definitions.

200: Request succeeded;
Non-200: Request failed.

message string

API response message. Usually success for a successful request.

data.task_id string

Image compression task ID. If the task fails, contact support with this task_id.

data.created_at string

Timestamp of task creation.

data.processed_at string

Timestamp when the task started to be processed.

data.completed_at string

Timestamp of task completion.

data.image string

Compressed result image URL or base64 data. The URL is valid for 1 hour.

data.progress number

Task progress.

100: Processing is complete.

data.state number

Task status code. See Status Code Definitions.

1: Succeeded;
> 1: Processing;
< 0: Failed;
-7: Invalid image file.

Guidelines and Limits

The result image URL is valid for 1 hour. Please download and store it promptly.
HTTP status 200 indicates that the HTTP request succeeded, not that image compression succeeded. Determine the task result with data.state. See Status Code Definitions.
When passing URLs as parameters, follow URL encoding standards to prevent parameter parsing confusion.
Use either image_url or image_file. If one image source parameter is present, the other image source parameter must be empty.
quality and kbyte cannot be sent together. If kbyte is used to specify a target size, PNG output does not support target-size compression.
Each successful request consumes 1 credit when the longest side is up to 4096px, or 2 credits when the longest side is greater than 4096px and up to 8000px.
Uploaded images must meet the following format, resolution, and file size limits.

Format Resolution Size

jpg, jpeg, bmp, png, webp, tiff, bitmap, gif, lzw, raw, rgb Up to 8000 x 8000 Up to 20MB

Format	Resolution	Size
jpg, jpeg, bmp, png, webp, tiff, bitmap, gif, lzw, raw, rgb	Up to 8000 x 8000	Up to 20MB

Response

{
  "status": 200,
  "message": "success",
  "data": {
    "task_id": "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "created_at": "1634884056", // Only present in async polling results.
    "processed_at": "1634884056", // Only present in async polling results.
    "completed_at": "1634884056", // Only present in async polling results.
    "image": "https://wxtechhk.oss-hongkong.aliyuncs.com/tasks/output/imgcompress/93a5e47b-a9c1-47ac-9b5e-22cb89f7d358-image.jpg", // Only present in async polling results.
    "progress": 100, // Only present in async polling results.
    "state": 1 // Only present in async polling results.
  }
}