MegaOptim
Back to Blog Tutorials

Getting Started with the MegaOptim Image Optimization API

· 7 min read

Getting Started with the MegaOptim Image Optimization API

If you have ever needed to optimize images at scale, whether for a custom CMS, a CI/CD pipeline, or a SaaS platform, you know that bolting together command-line tools and writing wrapper scripts gets tedious fast. The MegaOptim image optimization API gives you a single REST endpoint that handles compression, format conversion, and quality tuning, all accessible with a standard HTTP request.

In this tutorial, we will walk through everything you need to start using the API: obtaining an API key, submitting your first image, polling for results, and tuning compression to fit your needs.

What the MegaOptim API Does

At its core, the MegaOptim API is a REST API for image compression and conversion. You send it an image, choose a compression level, and get back an optimized version. Behind the scenes, the API uses SSIM-based binary search to find the smallest possible file size without dropping below a perceptual quality threshold. You can read more about how this works in our article on SSIM-driven compression.

The API supports JPEG, PNG, GIF, WebP, and AVIF. It can optimize images in their original format or convert between formats, so you can, for example, submit a JPEG and receive a WebP back.

This is the same engine that powers the MegaOptim WordPress plugin under the hood. Every image the plugin optimizes goes through this API. By using the API directly, you get the same optimization quality with full control over integration.

Authentication

The API uses key-based authentication. Every request must include your API key in a header. Once you sign up at app.megaoptim.com, you will find your key on the dashboard.

All authenticated requests use the X-API-Key header:

X-API-Key: your-api-key-here

Keep your API key private. Do not commit it to version control or expose it in client-side code.

The Basic Workflow

The optimization flow follows three steps:

  1. Submit an image via a POST request.
  2. Receive a request ID in the response.
  3. Poll the result endpoint until the optimization is complete.

This asynchronous design means the API can handle large images and complex conversions without forcing you to hold a connection open. Let’s walk through each step with cURL.

Step 1: Submit an Image

Send your image as a multipart form upload to the optimize endpoint:

curl -X POST https://api.megaoptim.com/v1/optimize 
  -H "X-API-Key: your-api-key-here" 
  -F "[email protected]" 
  -F "compression=intelligent"

The response includes a request ID:

{
  "status": "processing",
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Step 2: Poll for the Result

Use the request ID to check on your optimization:

curl https://api.megaoptim.com/v1/optimize/a1b2c3d4-e5f6-7890-abcd-ef1234567890/result 
  -H "X-API-Key: your-api-key-here"

While processing, you will receive:

{
  "status": "processing",
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Once complete:

{
  "status": "done",
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "original_size": 2458624,
  "optimized_size": 812033,
  "saved_bytes": 1646591,
  "saved_percent": 66.97,
  "result_url": "https://api.megaoptim.com/v1/optimize/a1b2c3d4-e5f6-7890-abcd-ef1234567890/download"
}

Step 3: Download the Optimized Image

curl -O -J https://api.megaoptim.com/v1/optimize/a1b2c3d4-e5f6-7890-abcd-ef1234567890/download 
  -H "X-API-Key: your-api-key-here"

In practice, you would wrap the polling step in a loop with a short delay. Most images complete within a few seconds.

Compression Levels

The API offers three compression levels, each targeting a different balance between file size and visual quality:

Level Parameter Value Description
Ultra ultra Aggressive compression for maximum file size reduction. Best for thumbnails and non-critical images.
Intelligent intelligent Balanced compression that preserves visual quality while significantly reducing size. The default and recommended choice for most use cases.
Lossless lossless No perceptual quality loss. Applies lossless optimization techniques to reduce size without altering pixels.

Pass your choice using the compression parameter:

curl -X POST https://api.megaoptim.com/v1/optimize 
  -H "X-API-Key: your-api-key-here" 
  -F "[email protected]" 
  -F "compression=ultra"

For lossy formats like JPEG, WebP, and AVIF, the intelligent and ultra levels use SSIM-guided quality search to find the optimal quality setting automatically. You do not need to guess at quality values.

Format Conversion

The API can convert images between formats in the same request. Add the convert_to parameter to specify your target format:

curl -X POST https://api.megaoptim.com/v1/optimize 
  -H "X-API-Key: your-api-key-here" 
  -F "[email protected]" 
  -F "compression=intelligent" 
  -F "convert_to=webp"

Supported target formats are jpeg, png, webp, and avif. This is particularly useful when you want to serve modern formats like WebP or AVIF to browsers that support them. If you are deciding which format is right for your project, our format comparison guide covers the trade-offs in detail.

Common Use Cases

The REST API design makes the MegaOptim image optimization API a natural fit for a variety of integration scenarios:

CI/CD Pipelines. Add an optimization step to your build process so that every image committed to your repository is compressed before deployment. A simple shell script calling the API can process an entire directory of assets during your build.

Custom CMS Integration. If you run a CMS that is not WordPress, you can integrate the API into your media upload handler. Optimize images on upload so that editors never have to think about file sizes.

Batch Processing. Need to optimize an existing library of thousands of images? Write a script that submits images in parallel, collects request IDs, and polls for results. The asynchronous design means you can have many optimizations in flight at once.

SaaS Platforms. If your product accepts user-uploaded images, such as an e-commerce platform, a social network, or a design tool, the API lets you optimize every upload on the fly, reducing storage costs and improving page load times for your users.

Static Site Generators. Hook into your build step for Hugo, Eleventy, or Jekyll to compress all images before generating your final site output.

Putting It Together

Here is a minimal bash script that submits an image, polls until it is ready, and downloads the result:

#!/bin/bash
API_KEY="your-api-key-here"
IMAGE_FILE="$1"

# Submit
RESPONSE=$(curl -s -X POST https://api.megaoptim.com/v1/optimize 
  -H "X-API-Key: $API_KEY" 
  -F "file=@$IMAGE_FILE" 
  -F "compression=intelligent")

REQUEST_ID=$(echo "$RESPONSE" | jq -r '.request_id')
echo "Submitted. Request ID: $REQUEST_ID"

# Poll
while true; do
  RESULT=$(curl -s "https://api.megaoptim.com/v1/optimize/$REQUEST_ID/result" 
    -H "X-API-Key: $API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.status')

  if [ "$STATUS" = "done" ]; then
    SAVED=$(echo "$RESULT" | jq -r '.saved_percent')
    echo "Optimization complete. Saved ${SAVED}%"
    break
  fi
  sleep 2
done

# Download
curl -s -O -J "https://api.megaoptim.com/v1/optimize/$REQUEST_ID/download" 
  -H "X-API-Key: $API_KEY"

echo "Optimized file downloaded."

This pattern adapts easily to any language. The API speaks plain HTTP and JSON, so whether you are working in Python, Node.js, Go, or PHP, integration is straightforward.

Get Started

The MegaOptim image optimization API is ready to integrate into your workflow today. Sign up at app.megaoptim.com to get your API key and start optimizing. The free tier gives you enough credits to test your integration thoroughly before scaling up.

If you have questions about specific integration patterns or need help with your setup, reach out through the dashboard. We are happy to help you get the most out of the API.