Automatic optimization documentation

How it works

Your website sends one JPG or PNG image with an API token, and Imageonix returns JSON with the applied mode, file size statistics, and a temporary download URL. Auto mode detects Ultra HDR JPG files and preserves their HDR information automatically.

API access requires an account token. Create or access your token from the account page.

Privacy and download lifetime

The uploaded original is removed immediately after processing. The optimized result and its download URL remain available for up to 15 minutes, after which the file is automatically deleted.

Download the result immediately after a successful API response.

Ready PHP file for your website

Your website can be a CMS, online store, custom PHP project, or even a simple static HTML website.

Place the ready Imageonix PHP file in your website, set the API token, image folder, and optimization mode, then run the file manually or through a Cron job.

Download the ready PHP file

The archive contains the ready PHP file and a short README with the first steps.

Requirements for your website

The example code is intended for PHP 7.4+ or PHP 8.x with active cURL. Requests are sent as multipart/form-data.

We do not recommend an official integration for old PHP 5 environments. The hosting account should be upgraded to a supported PHP version.

Endpoint

POST https://imageonix.com/api/optimize.php

Send the token with an HTTP header:

Authorization: Bearer YOUR_API_TOKEN

Fields:

The recommended auto mode selects hdr for Ultra HDR JPG files and balanced for all other files. If hdr is explicitly requested for a regular JPG or PNG, balanced is applied. Explicitly selecting a standard mode for an Ultra HDR JPG creates a standard SDR result without HDR information.

What is configured in the ready file

What happens with already optimized images

The ready file works in batches and skips images that have already been processed by Imageonix.

If you edit an already processed image, the system will recognize it as changed and optimize it again on a later run.

Limits and tokens

Each account has a monthly limit of 500 successful optimizations. The limit is counted by calendar month.

One account can have up to 3 active API tokens. The full token is shown only once when it is created.

Tokens can be disabled and enabled from the account page. A disabled token cannot make API requests.

Imageonix may temporarily limit a token or IP address after too many failed requests in a short period.

PHP example

The example is for PHP 7.4+ and PHP 8.x with active cURL.

$ch = curl_init('https://imageonix.com/api/optimize.php');

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_API_TOKEN',
    ],
    CURLOPT_POSTFIELDS => [
        'mode' => 'auto',
        'image' => new CURLFile('/path/to/image.jpg'),
    ],
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$curlError = curl_error($ch);
curl_close($ch);

if ($response === false) {
    throw new RuntimeException('Request failed: ' . $curlError);
}

$data = json_decode($response, true);

if ($httpCode === 200 && !empty($data['success'])) {
    echo 'Saved: ' . $data['saved_percent'] . "%\n";
    echo 'Download: ' . $data['download_url'] . "\n";
} else {
    $message = $data['message'] ?? $data['error'] ?? 'Unknown API error';
    echo 'Imageonix error: ' . $message . "\n";
}

Successful JSON response

{
  "success": true,
  "request_id": "req_20260706_xxxxx",
  "requested_mode": "auto",
  "mode": "hdr",
  "source_is_ultra_hdr": true,
  "method": "ultrahdr_mozjpeg_q70_gainmap_q85",
  "original_size": 1250000,
  "optimized_size": 420000,
  "saved_bytes": 830000,
  "saved_percent": 66.4,
  "usage": {
    "total_requests": 1542,
    "month_requests": 37,
    "monthly_limit": 500,
    "remaining_this_month": 463
  },
  "download_expires_in_seconds": 900,
  "download_url": "https://imageonix.com/api/download.php?request_id=...&token=..."
}

JSON error response

{
  "success": false,
  "error": "monthly_limit_reached",
  "message": "Monthly request limit reached.",
  "usage": {
    "total_requests": 1542,
    "month_requests": 500,
    "monthly_limit": 500,
    "remaining_this_month": 0
  }
}

Main error codes

How the ready file can be started

php /home/USERNAME/public_html/imageonix-optimize.php

/usr/local/bin/php /home/USERNAME/public_html/imageonix-optimize.php

/opt/remi/php85/root/bin/php /home/USERNAME/public_html/imageonix-optimize.php

If you do not know the exact PHP CLI path, ask your hosting support. The first test should use a small limit and should be done after a backup.