# Image Compression
Compress and resize JPEG, PNG, or WebP images.
## API Overview
- **HTTP Protocol:** HTTPS
- **HTTP Method:** POST
- **HTTP Endpoint:** https://api.gugudata.io/v1/image/image-compress
- **Response Type:** Binary stream on success; application/json on authentication or validation errors
- **DEMO Endpoint:** https://api.gugudata.io/v1/image/image-compress/demo
- **Live Demo:** https://gugudata.io/demo/image-compress
- **Postman:** https://www.postman.com/gugudata/gugudata-io
- **LLM Page:** https://gugudata.io/details/image-compress/llm
- **Raw Markdown:** https://gugudata.io/details/image-compress/llm.md
## Remote MCP
- **MCP Endpoint:** https://mcp.gugudata.io/mcp
- **MCP Guide:** https://gugudata.io/mcp/
- **Authorization:** OAuth authorization opens in the browser; do not paste appkeys into MCP clients.
- **Tool Scope:** MCP clients receive GuGuData API tools available to the authorized account.
## Data & API Features
- Uploads and public image URLs: Optimize files supplied by users or images already available through a public HTTP(S) URL.
- JPEG, PNG, and WebP: Accept the three common web image formats and choose the output format your workflow needs.
- Aspect-ratio-preserving resize: Fit images within target dimensions without distortion or unnecessary upscaling.
- Quality control: Balance file size and visual quality for JPEG and WebP while keeping PNG output lossless.
- Direct optimized image bytes: Receive the processed image with the correct media type and a usable download filename.
- Faster media delivery: Reduce image payloads for websites, mobile apps, storage, email, archives, and publishing pipelines.
## API Request Parameters
| Name | Type | Is Required | Default Value | Remark |
| --- | --- | --- | --- | --- |
| appkey | string | true | YOUR_APPKEY | API key used to authenticate the request. |
| file | file | false | | JPEG, PNG, or WebP multipart upload up to 10 MiB. Supply either file or image_url, but not both. |
| image_url | string | false | | Complete public HTTP or HTTPS image URL up to 2,048 characters. Supply either image_url or file, but not both. |
| targetWidth | integer | false | | Output width bound from 1 to 8,192 pixels. Aspect ratio is preserved and smaller images are not enlarged. |
| targetHeight | integer | false | | Output height bound from 1 to 8,192 pixels. Aspect ratio is preserved and smaller images are not enlarged. |
| maxWidth | integer | false | | Maximum output width from 1 to 8,192 pixels while preserving aspect ratio. |
| maxHeight | integer | false | | Maximum output height from 1 to 8,192 pixels while preserving aspect ratio. |
| quality | integer | false | 85 | JPEG or WebP output quality from 1 to 95. PNG output remains lossless. |
| format | string | false | | Output format: jpeg, jpg, png, or webp. The source format is used when omitted. |
## API Response Parameters
| Name | Type | Remark |
| --- | --- | --- |
| image | binary | Compressed image bytes. The response media type and download filename match the selected output format. |
## API Response Status Codes
| Status Code | Explanation of Status Code | Remarks |
| --- | --- | --- |
| 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 request frequency and retry with backoff. If a trial allowance is exhausted, check Trial Keys for remaining requests and subscribe to continue. |
| 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. |
## cURL Example
```bash
curl --location 'https://api.gugudata.io/v1/image/image-compress?appkey=YOUR_APPKEY' --form 'file=@localfile_path.png' --form 'quality=85'
```