Image Optimizer API Documentation

Introduction

The Image Optimizer API allows you to integrate image optimization capabilities into your own platform. With this API, you can automatically compress and optimize images, reducing file sizes while maintaining quality.

This API is designed to be easy to use and integrate with your existing systems. It supports various image formats, including JPEG, PNG, WebP, and AVIF, and provides options for resizing and quality adjustment.

Authentication

All API requests require an API key for authentication. You can obtain an API key by registering for an account and generating a key in your dashboard.

To authenticate your requests, include your API key in the X-API-Key header:

X-API-Key: your_api_key_here

Base URL

All API endpoints are relative to the base URL:

https://imgoptimizer.vercel.app/api/v1

Endpoints

Optimize a Single Image

POST /optimize

Optimizes a single image. Supports both form data and JSON requests.

Form Data Request

Parameters:

image (required) - The image file to optimize
quality (optional) - The quality level (1-100, default: 80)
width (optional) - The target width in pixels
height (optional) - The target height in pixels
format (optional) - The output format (webp, jpeg, png, avif, default: webp)

JSON Request

Example request body:

{
  "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD...",
  "quality": 80,
  "width": 800,
  "height": 600,
  "format": "webp"
}

Response

Example response:

{
  "success": true,
  "originalSize": 1024000,
  "optimizedSizeBytes": 102400,
  "originalSizeFormatted": "1.0 MB",
  "optimizedSizeFormatted": "100.0 KB",
  "savings": 921600,
  "savingsPercentage": "90.00",
  "format": "webp",
  "width": 800,
  "height": 600,
  "quality": 80,
  "optimizedImage": "data:image/webp;base64,UklGRjYAAABXRUJQVlA4..."
}

Batch Optimize Images

POST /optimize/batch

Optimizes multiple images in a single request.

Request

Example request body:

{
  "quality": 80,
  "format": "webp",
  "images": [
    {
      "data": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD...",
      "quality": 85  // Override global quality for this image
    },
    {
      "data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...",
      "width": 400,
      "height": 300
    }
  ]
}

Response

Example response:

{
  "success": true,
  "totalImages": 2,
  "successfulImages": 2,
  "failedImages": 0,
  "totalOriginalSize": 2048000,
  "totalOptimizedSize": 204800,
  "totalSavings": 1843200,
  "totalSavingsPercentage": "90.00",
  "totalOriginalSizeFormatted": "2.0 MB",
  "totalOptimizedSizeFormatted": "200.0 KB",
  "totalSavingsFormatted": "1.8 MB",
  "results": [
    {
      "index": 0,
      "success": true,
      "originalSize": 1024000,
      "optimizedSizeBytes": 102400,
      "originalSizeFormatted": "1.0 MB",
      "optimizedSizeFormatted": "100.0 KB",
      "savings": 921600,
      "savingsPercentage": "90.00",
      "format": "webp",
      "width": "original",
      "height": "original",
      "quality": 85,
      "optimizedImage": "data:image/webp;base64,UklGRjYAAABXRUJQVlA4..."
    },
    {
      "index": 1,
      "success": true,
      "originalSize": 1024000,
      "optimizedSizeBytes": 102400,
      "originalSizeFormatted": "1.0 MB",
      "optimizedSizeFormatted": "100.0 KB",
      "savings": 921600,
      "savingsPercentage": "90.00",
      "format": "webp",
      "width": 400,
      "height": 300,
      "quality": 80,
      "optimizedImage": "data:image/webp;base64,UklGRjYAAABXRUJQVlA4..."
    }
  ]
}

Webhook Integration

POST /webhook

Optimizes an image from a URL and optionally sends the result to a callback URL.

Request

Example request body:

{
  "imageUrl": "https://example.com/image.jpg",
  "quality": 80,
  "width": 800,
  "height": 600,
  "format": "webp",
  "callbackUrl": "https://your-server.com/webhook-callback"
}

Response

Example response with callback URL:

{
  "success": true,
  "message": "Image optimization request received. Results will be sent to the callback URL.",
  "requestId": "a1b2c3d4e5f6"
}

Example response without callback URL (same as single image optimization):

{
  "success": true,
  "originalSize": 1024000,
  "optimizedSizeBytes": 102400,
  "originalSizeFormatted": "1.0 MB",
  "optimizedSizeFormatted": "100.0 KB",
  "savings": 921600,
  "savingsPercentage": "90.00",
  "format": "webp",
  "width": 800,
  "height": 600,
  "quality": 80,
  "optimizedImage": "data:image/webp;base64,UklGRjYAAABXRUJQVlA4...",
  "originalUrl": "https://example.com/image.jpg",
  "requestId": "a1b2c3d4e5f6"
}

API Key Management

POST /keys

Generates a new API key.

Request

Example request body:

{
  "userId": "user123",
  "name": "My API Key"
}

Response

Example response:

{
  "success": true,
  "apiKey": {
    "id": "key123",
    "key": "abcdef123456",
    "name": "My API Key",
    "createdAt": "2023-06-01T12:00:00Z",
    "permissions": ["optimize"],
    "rateLimit": 100
  }
}

API Key Usage

GET /keys

Gets usage statistics for an API key.

Request

Include your API key in the X-API-Key header.

Response

Example response:

{
  "success": true,
  "usage": {
    "totalRequests": 100,
    "totalOptimizedImages": 150,
    "totalSavings": 104857600,
    "lastUsed": "2023-06-01T12:00:00Z"
  }
}

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request. In case of an error, the response will include an error message and, when available, additional details.

Example error response:

{
  "error": "Failed to optimize image",
  "details": "Invalid image format"
}

Common Error Codes

400 Bad Request - The request was invalid or missing required parameters
401 Unauthorized - Invalid or missing API key
415 Unsupported Media Type - Unsupported content type
500 Internal Server Error - An error occurred on the server

Rate Limiting

The API is rate limited to prevent abuse. The rate limit depends on your subscription plan. If you exceed the rate limit, you will receive a 429 Too Many Requests response.

Client Libraries

We provide client libraries for easy integration with your application:

JavaScript/TypeScript: npm install @imgoptimizer/client
Python: pip install imgoptimizer-client
PHP: composer require imgoptimizer/client

Support

If you have any questions or need help with the API, please contact our support team at support@imgoptimizer.com.