API Documentation

Authentication

All optimization and result endpoints require an API key passed via the X-API-KEY header.

X-API-KEY: your_api_key_here

Get your API key from your dashboard.

Schedule one or more images for optimization. Returns a process_id to poll for results.

Requires authentication. Rate limit: 120 requests/minute.

Request Parameters

Compression Levels

Supported formats: JPEG, PNG, GIF, WebP, AVIF

Example: Optimize by URL

curl -X POST https://api.megaoptim.com/v1/optimize \
  -H "X-API-KEY: your_api_key" \
  -F "type=url" \
  -F "url=https://example.com/photo.jpg" \
  -F "compression=medium"

Example: Upload & Convert to WebP

curl -X POST https://api.megaoptim.com/v1/convert \
  -H "X-API-KEY: your_api_key" \
  -F "type=file" \
  -F "file=@/path/to/image.jpg" \
  -F "compression=high" \
  -F "format=webp"

Success Response (202)

{
    "status": "processing",
    "code": 202,
    "process_id": 12345
}

Error Response (400)

{
    "status": "error",
    "code": 400,
    "errors": [
        "The type field is required and must be one of: url, file, urls, files."
    ]
}

Long-polls for the optimization result. The server holds the connection open until the result is ready or the timeout is reached.

Requires authentication. Rate limit: 350 requests/minute.

Request Parameters

Success Response (200)

{
    "status": "ok",
    "code": 200,
    "result": [
        {
            "success": true,
            "file_name": "photo.jpg",
            "original_size": 524288,
            "optimized_size": 314572,
            "saved_bytes": 209716,
            "saved_percent": 40.0,
            "url": "https://cdn.example.com/abc123/photo.jpg",
            "type": "compress",
            "format": "jpg"
        }
    ],
    "id": 12345,
    "user": {
        "name": "John Doe",
        "email": "[email protected]",
        "tokens": 4500
    }
}

Result Object Fields

WebP Object (when present)

User Object

Error Responses

{
    "status": "error",
    "errors": ["Job not found."],
    "code": 404
}

{
    "status": "error",
    "errors": ["Access denied. This optimization request does not belong to your account."],
    "code": 401
}

{
    "status": "error",
    "errors": ["Request timeout! The max timeout of 80 seconds was reached."],
    "code": 504
}

{
    "status": "error",
    "code": 500,
    "errors": ["Optimization failure. Possible internal server error. Please contact support for more information."]
}

Download an optimized image file. The full URL is provided in the result object's url field.

No authentication required. Returns the image with the appropriate Content-Type header.

Supported output types: JPEG, PNG, GIF, WebP, AVIF, SVG. Returns 404 if the file is not found.

Error Codes

Authentication Error Examples

{
    "status": "error",
    "code": 465,
    "errors": ["Missing API key. Make sure you copy the correct API key from https://megaoptim.com/dashboard or if you do not have one, sign up at https://megaoptim.com"]
}

{
    "status": "error",
    "code": 404,
    "errors": ["Invalid API key. You can always signup on our site https://megaoptim.com and choose your plan."]
}

{
    "status": "error",
    "code": 466,
    "errors": ["No tokens left. Please top up your account at https://megaoptim.com/dashboard in order to continue."]
}