API Reference

v1.0

Integrate Smolpix image optimization into your applications with our RESTful API.

Introduction

The Smolpix API allows you to programmatically optimize images using our powerful compression engine. Convert images to WebP or AVIF format, resize them, and apply smart compression based on image content.

Pro Plan Required

API access is available on Pro ($49/mo) and Agency ($149/mo) plans.Upgrade your plan

Authentication

All API requests must include an API key in the Authorization header. You can create and manage API keys from your Dashboard.

Authorization Header

http

Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxx

API Key Format

•Keys start with pk_live_ prefix
•Keys are shown only once when created - save them securely
•Maximum 5 API keys per account
•Keys can be revoked anytime from the dashboard

Rate Limits

Rate limits vary by plan. When you exceed your rate limit, the API returns a 429 error.

Plan	Requests/Minute	Images/Month
Pro	60	10,000
Agency	120	Unlimited

Rate Limit Response

When rate limited, wait before retrying. The response includes your current usage.

Optimize Image

POST/api/v1/optimize

Optimize an image from a URL. The API fetches the image, applies optimization, and returns the optimized image as base64-encoded data.

Request Body

Parameter	Type	Default	Description
`url`*	string	-	URL of the image to optimize
`format`	string	auto	Output format: 'auto', 'webp', or 'avif'
`quality`	number	80	Compression quality (1-100)
`maxWidth`	number	1920	Maximum width in pixels (maintains aspect ratio)
`smart`	boolean	true	Use smart compression based on image content

Example Request

json

{
  "url": "https://example.com/photo.jpg",
  "format": "auto",
  "quality": 80,
  "maxWidth": 1920,
  "smart": true
}

Response

Field	Type	Description
`success`	boolean	Whether optimization succeeded
`originalSize`	number	Original file size in bytes
`optimizedSize`	number	Optimized file size in bytes
`savings`	number	Bytes saved
`savingsPercent`	number	Percentage saved (0-100)
`format`	string	Output format (webp or avif)
`width`	number	Output width in pixels
`height`	number	Output height in pixels
`data`	string	Base64-encoded image data
`contentType`	string	MIME type (image/webp or image/avif)

Example Response

json

{
  "success": true,
  "originalSize": 1234567,
  "optimizedSize": 234567,
  "savings": 1000000,
  "savingsPercent": 81,
  "format": "avif",
  "width": 1920,
  "height": 1080,
  "data": "AAAAIGZ0eXBhdmlmAAAAAGF2aWZtaWYx...",
  "contentType": "image/avif"
}

Error Handling

The API uses standard HTTP status codes. Error responses include a message explaining the issue.

Status	Code	Description
400	`Bad Request`	Missing required parameters or invalid URL
401	`Unauthorized`	Missing or invalid API key
403	`Forbidden`	API access requires Pro plan or higher
429	`LIMIT_REACHED`	Rate limit or monthly quota exceeded
500	`Server Error`	Internal server error during optimization

Error Response Example

json

{
  "error": "Monthly image limit reached",
  "code": "LIMIT_REACHED",
  "used": 10000,
  "limit": 10000
}

Code Examples

Node.js / JavaScript

javascript

const response = await fetch('https://smolpix.co/api/v1/optimize', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer pk_live_xxxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com/image.jpg',
    format: 'auto',
    quality: 80,
    smart: true,
  }),
});

const data = await response.json();

if (data.success) {
  // Convert base64 to buffer
  const buffer = Buffer.from(data.data, 'base64');

  // Save to file
  fs.writeFileSync('optimized.webp', buffer);

  console.log(`Saved ${data.savingsPercent}% - ${data.originalSize} → ${data.optimizedSize}`);
}

Python

python

import requests
import base64

response = requests.post(
    'https://smolpix.co/api/v1/optimize',
    headers={
        'Authorization': 'Bearer pk_live_xxxxxxxxxxxxxxxxxxxxx',
        'Content-Type': 'application/json',
    },
    json={
        'url': 'https://example.com/image.jpg',
        'format': 'auto',
        'quality': 80,
        'smart': True,
    }
)

data = response.json()

if data.get('success'):
    # Decode base64 and save
    image_data = base64.b64decode(data['data'])

    with open('optimized.webp', 'wb') as f:
        f.write(image_data)

    print(f"Saved {data['savingsPercent']}%")

cURL

bash

curl -X POST https://smolpix.co/api/v1/optimize \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/image.jpg",
    "format": "auto",
    "quality": 80,
    "smart": true
  }'

PHP

php

<?php
$ch = curl_init('https://smolpix.co/api/v1/optimize');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxx',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'url' => 'https://example.com/image.jpg',
        'format' => 'auto',
        'quality' => 80,
        'smart' => true,
    ]),
]);

$response = curl_exec($ch);
$data = json_decode($response, true);

if ($data['success']) {
    $imageData = base64_decode($data['data']);
    file_put_contents('optimized.webp', $imageData);
    echo "Saved {$data['savingsPercent']}%";
}
?>

Ready to get started?

Create your API key and start optimizing images programmatically.

Create API Key View Plans