Image Compress

Image Compression
Compress and optionally resize an uploaded image or a remote image URL, then return the compressed binary stream on success.

Method: POST
Path: /v1/image/image-compress
Demo: https://api.gugudata.io/v1/image/image-compress/demo
OpenAPI: https://gugudata.io/assets/openapi/gugudata.openapi.3.1.json

Request Parameters:

appkey (string, required): Application key used for request authentication. Supply the value as a query parameter, form field, or multipart field according to the request content type.

file (file, optional): Image file uploaded as multipart form data. Supply either file or image_url, but not both.

image_url (string, optional): Remote image URL to compress. Supply either image_url or file, but not both.

targetWidth (integer, optional): Exact output width in pixels.

targetHeight (integer, optional): Exact output height in pixels.

maxWidth (integer, optional): Maximum output width in pixels while preserving aspect ratio.

maxHeight (integer, optional): Maximum output height in pixels while preserving aspect ratio.

quality (integer, optional): Compression quality or output quality level accepted by the endpoint.

format (string, optional): Requested output format when the endpoint supports explicit format conversion.

Response Fields:

image (binary, required): Compressed image binary stream returned on success. On failure, the endpoint returns a JSON error payload instead of binary content.

HTTP Status Codes:

200: Request processed successfully. Some endpoints expose a separate application-level status field in the response body, such as dataStatus.statusCode.

400: Invalid request parameters or request format. Check required fields, data types, and request body format.

401: Missing or unknown application key. Provide a valid appkey with the request.

403: The application key is recognized but access is not allowed. The key may be expired, inactive, or not permitted for the requested API.

429: Request rate or trial usage limit exceeded. Reduce concurrency or retry after the limit window resets.

500: Internal service error. Retry later or contact support if the error persists.

503: Upstream service unavailable. Retry later; the requested upstream dependency is temporarily unavailable.

Business Status Codes:

200 Normal return: Image successfully compressed and returned as binary stream

400 Parameter error: Invalid or missing required parameters. Either file or image_url must be provided, but not both. Quality must be between 1 and 95

429 Request frequency limited: Cannot exceed 100 requests per second

403 Account in arrears: Payment required to continue using the service

402 APPKEY error: Please check whether the APPKEY passed is obtained from the developer center

500 API response error: Internal server error during image processing. Image format may be unsupported or file may be corrupted

503 Service unavailable: External service temporarily unavailable

Key Features:

Support both file upload and URL-based image processing.

Intelligent compression with customizable quality (1-95).

Flexible dimension control with target size and max size options.

Automatic aspect ratio preservation during resizing.

Format conversion support (JPEG, PNG, etc.).

Optimized compression algorithms for maximum file size reduction.

Support for large images up to 10MB.

Full API support for HTTPS (TLS v1.0 / v1.1 / v1.2 / v1.3).

Fully compatible with Apple ATS.

Nationwide multi-node CDN deployment.

Ultra-fast response, API interface load balancing built with multiple servers.

Perfect for web optimization, mobile apps, and content management systems.

Details:
https://gugudata.io/details/image-compress

application/json

Bodyapplication/json

Example

{
  "image": null,
  "DataStatus": {
    "StatusCode": 100,
    "StatusDescription": "OK",
    "ResponseDateTime": "2026-01-01 00:00:00",
    "DataTotalCount": 1
  }
}

Request

Request Code Samples

Responses