Compress Image

Reduce the file size of an image while maintaining acceptable visual quality, with options for quality level and maximum file size.

Request Parameters

Response

Returns the compressed image in the specified or original format.

Example Request

    // example.sh
curl -X POST "https://oyyi.xyz/api/image/compress"   -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@image.jpg" \
  -F "quality=70" \
  --output compressed.jpg
  

Example with Python

    // compress.py
import requests

url = "https://oyyi.xyz/api/image/compress"

files = {
    'file': open('image.jpg', 'rb')
}

data = {
    'quality': 70
}

response = requests.post(url, files=files, data=data)

# Save the compressed image
with open('compressed.jpg', 'wb') as f:
    f.write(response.content)
  

Example with JavaScript

    // compress.js
// Using fetch API
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('quality', '75');
formData.append('max_size_kb', '200');

fetch('https://oyyi.xyz/api/image/compress', {
  method: 'POST',
  body: formData
})
.then(response => response.blob())
.then(blob => {
  // Create a URL for the blob
  const url = URL.createObjectURL(blob);

  // Create a link to download the image
  const a = document.createElement('a');
  a.href = url;
  a.download = 'compressed.jpg';
  a.click();

  // Clean up by revoking the URL
  URL.revokeObjectURL(url);
})
.catch(error => console.error('Error:', error));
  

Compression Strategies

Quality Levels

How It Works

The compress endpoint reduces the file size of an image using various techniques:

1. Image Loading: The uploaded image is loaded into memory.
2. Format Detection: The image format is detected to determine the optimal compression method.
3. Specialized Compression: Format-specific external tools are used for optimal compression:
   • JPEG: jpegoptim for superior JPEG compression
   • PNG: pngquant for efficient lossy PNG compression
   • GIF: gifsicle for GIF optimization
   • WebP: cwebp (from libwebp) for WebP compression
4. Format Selection: If output_format is specified, the image is prepared for conversion to that format. Otherwise, the original format is used (or JPEG for formats that don't compress well).
5. Metadata Handling: If strip_metadata is true (default), EXIF and other metadata are removed from the image.
6. Initial Compression: The image is compressed using the specified quality level.
7. Size Check: If max_size_kb is specified, the resulting file size is checked against this limit.
8. Iterative Compression: If the file is still too large:
   • If resize is true, the image dimensions are reduced while maintaining aspect ratio, up to the specified max_width and max_height.
   • The quality level is automatically adjusted in multiple passes to achieve the target file size.
   • If the target size cannot be achieved even with minimum quality and resizing, the smallest possible version is returned.

The result is an image with a reduced file size that maintains an acceptable level of visual quality based on the specified parameters.

Format Recommendations

Error Responses

Notes

• The API uses specialized external tools (jpegoptim, pngquant, gifsicle, cwebp) for optimal compression when available.
• The compression process is lossy for JPEG and WebP formats, meaning some image data is permanently discarded to reduce file size.
• PNG compression with pngquant is lossy but visually lossless, providing much better compression than traditional lossless PNG compression.
• Stripping metadata can significantly reduce file size, especially for photos from digital cameras that contain extensive EXIF data.
• When specifying max_size_kb, be realistic about the target size based on the image dimensions and content. Very low values may result in poor quality.
• If both quality and max_size_kb are specified, the quality parameter serves as the initial quality level, which may be automatically reduced to meet the size requirement.
• The maximum file size allowed for input is 50MB.
• For transparent images (PNG, WebP), converting to JPEG will replace transparency with a white background.

Use Cases

• Optimizing images for web pages to improve loading speed
• Reducing file size for email attachments
• Preparing images for upload to social media platforms with size limits
• Creating optimized image assets for mobile applications
• Batch processing large collections of images to save storage space
• Generating thumbnails or previews with small file sizes
• Meeting specific file size requirements for submissions or uploads
• Reducing bandwidth usage for image-heavy applications