API Documentation

The K-Means Image Compressor provides a RESTful API for programmatic image compression. All endpoints return JSON responses and support CORS.

Health Check

Check if the API service is running and healthy.

{
    "status": "healthy",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "version": "1.0.0"
}

Upload Image

Upload an image for later compression. Returns an image ID for subsequent operations.

curl -X POST \
  -F "image=@photo.jpg" \
  https://your-domain.com/api/upload

{
    "success": true,
    "image_id": "20240115_103000_a1b2c3d4.jpg",
    "preview_url": "https://your-domain.com/api/original/20240115_103000_a1b2c3d4.jpg",
    "dimensions": {
        "width": 1920,
        "height": 1080
    },
    "format": "JPEG",
    "file_size": 524288
}

Compress Image

Compress a previously uploaded image using K-Means clustering.

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"image_id": "20240115_103000_a1b2c3d4.jpg", "n_colors": 16}' \
  https://your-domain.com/api/compress

{
    "success": true,
    "compressed_id": "compressed_20240115_103000_a1b2c3d4.jpg",
    "download_url": "https://your-domain.com/api/download/compressed_...",
    "preview_url": "https://your-domain.com/api/compressed/compressed_...",
    "stats": {
        "original_file_size": 524288,
        "compressed_file_size": 156432,
        "file_compression_ratio": 3.35,
        "theoretical_compression_ratio": 6.0,
        "original_colors": 45821,
        "reduced_colors": 16,
        "iterations": 8,
        "processing_time_ms": 1234.56
    }
}

Compress Direct

Upload and compress an image in a single request. Returns the compressed image directly.

curl -X POST \
  -F "image=@photo.jpg" \
  -F "n_colors=16" \
  -o compressed.png \
  https://your-domain.com/api/compress-direct

Get Presets

Get predefined compression presets for common use cases.

{
    "success": true,
    "presets": [
        {
            "name": "Maximum Compression",
            "description": "Smallest file size, reduced quality",
            "n_colors": 4,
            "max_iters": 15
        },
        {
            "name": "Balanced",
            "description": "Good balance of size and quality",
            "n_colors": 16,
            "max_iters": 10
        },
        ...
    ]
}

Error Handling

All API errors return a consistent JSON format with an error message.

Error Response Format

{
    "success": false,
    "error": "Descriptive error message"
}

Python Example

import requests

# Upload and compress an image
def compress_image(image_path, n_colors=16):
    base_url = "https://your-domain.com/api"
    
    # Upload
    with open(image_path, 'rb') as f:
        response = requests.post(
            f"{base_url}/upload",
            files={'image': f}
        )
    
    image_id = response.json()['image_id']
    
    # Compress
    response = requests.post(
        f"{base_url}/compress",
        json={
            'image_id': image_id,
            'n_colors': n_colors
        }
    )
    
    result = response.json()
    
    # Download
    download_url = result['download_url']
    img_response = requests.get(download_url)
    
    with open('compressed.png', 'wb') as f:
        f.write(img_response.content)
    
    return result['stats']

# Usage
stats = compress_image('photo.jpg', n_colors=16)
print(f"Compression ratio: {stats['file_compression_ratio']}x")

JavaScript Example

async function compressImage(file, nColors = 16) {
    const baseUrl = 'https://your-domain.com/api';
    
    // Upload
    const formData = new FormData();
    formData.append('image', file);
    
    const uploadResponse = await fetch(`${baseUrl}/upload`, {
        method: 'POST',
        body: formData
    });
    const { image_id } = await uploadResponse.json();
    
    // Compress
    const compressResponse = await fetch(`${baseUrl}/compress`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            image_id,
            n_colors: nColors
        })
    });
    
    return await compressResponse.json();
}

// Usage
const fileInput = document.querySelector('input[type="file"]');
fileInput.addEventListener('change', async (e) => {
    const result = await compressImage(e.target.files[0], 16);
    console.log(`Compressed! Ratio: ${result.stats.file_compression_ratio}x`);
});