API & SDK

Overview

SmallPict provides a powerful REST API and official SDKs for developers who want to integrate image optimization directly into their custom backends, far beyond just WordPress plugins.

By using the API, you can seamlessly compress, convert (to WebP, AVIF), and resize images on the fly before storing them in your own infrastructure or serving them through our upcoming CDN.

Authentication

All API requests require authentication using an API key. You can generate an API key from the API Keys section in your SmallPict Dashboard.

Security Best Practice: Never expose your API keys in frontend code (like React, Vue, or Vanilla JS). Always make requests to SmallPict from your backend server.

Pass your API key in the Authorization header as a Bearer token:

Authorization: Bearer sp_test_1234567890abcdef

REST API Endpoint

The primary endpoint for processing images is:

POST https://api.tuxnoob.com/v1/images/optimize

Request Parameters

• image: (Required) The image file to optimize (multipart/form-data).
• format: (Optional) Output format (e.g., webp, avif, jpg).
• quality: (Optional) Optimization quality from 50 to 100.

Example Request (cURL)

curl -X POST https://api.tuxnoob.com/v1/images/optimize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@/path/to/image.png" \
  -F "format=webp" \
  -F "quality=85"

Official SDKs (Coming Soon)

We are actively developing official SDKs to make integration even easier.

Node.js SDK

import { SmallPict } from '@smallpict/sdk';

const client = new SmallPict('YOUR_API_KEY');

const optimized = await client.images.optimize({
  file: buffer,
  format: 'webp',
  quality: 80
});

Python SDK

from smallpict import SmallPict

client = SmallPict(api_key="YOUR_API_KEY")

optimized = client.images.optimize(
    file=open("image.png", "rb"),
    format="webp",
    quality=80
)

Go SDK

import "github.com/tuxnoob/smallpict-sdk-go"

client := smallpict.NewClient("YOUR_API_KEY")

optimized, err := client.Images.Optimize(context.Background(), smallpict.OptimizeOptions{
    File:    fileBytes,
    Format:  "webp",
    Quality: 80,
})

PHP SDK

<?php
require 'vendor/autoload.php';

$client = new SmallPict\Client('YOUR_API_KEY');

$optimized = $client->images->optimize([
    'url' => 'https://example.com/photo.jpg',
    'format' => 'webp',
    'quality' => 'auto'
]);

echo $optimized->url;
?>

Java SDK

import com.smallpict.SmallPict;
import com.smallpict.models.OptimizeParams;

public class Main {
    public static void main(String[] args) {
        SmallPict client = new SmallPict("YOUR_API_KEY");
        
        var params = new OptimizeParams()
            .setUrl("https://example.com/photo.jpg")
            .setFormat("webp")
            .setQuality("auto");
            
        var optimized = client.images().optimize(params);
        System.out.println(optimized.getUrl());
    }
}

Ruby SDK

require 'smallpict'

client = SmallPict::Client.new(api_key: 'YOUR_API_KEY')

optimized = client.images.optimize(
  url: 'https://example.com/photo.jpg',
  format: 'webp',
  quality: 'auto'
)

puts optimized.url

Rate Limits & Quotas

• Quotas: Image optimization counts towards your monthly plan limit (e.g., 20 MB for Free Plan).
• Rate Limits: To ensure system stability, concurrent requests are limited. Exceeding the rate limit will return an HTTP 429 Too Many Requests status. Wait briefly before retrying.

Note: Internal rate limiting logic and headers are not exposed for security purposes.

URL Transformation Parameters

Pass these query parameters to https://cdn.tuxnoob.com/v1/transform for on-the-fly media manipulation.

Edge Response Headers

SmallPict appends useful performance and diagnostic headers to every response.

• x-smallpict-cache: HIT (Served directly from edge cache in 12ms)
• x-smallpict-original-size: 2450000 (Original upload size in bytes)
• x-smallpict-savings: 78% (Net percentage bandwidth saved)

API/SDK Pricing Plans

For developers building custom applications, SmallPict offers three dedicated tiers designed for scale:

• Ignite: Ideal for side projects and MVPs. Includes generous API quotas with BYOK (Bring Your Own Key) CDN routing.
• Velocity: Built for growing SaaS products. Higher API limits and advanced transformation features, using BYOK CDN.
• Momentum: Enterprise-grade performance. Includes unlimited API calls (subject to fair use) and a Fully-Managed CDN powered by SmallPict, so you don't need to bring your own Cloudflare account.

CDN Configuration: BYOK vs Managed

When integrating the SmallPict API/SDK, you have control over how optimized images are delivered to your end users:

Bring Your Own CDN (BYOK)

Available on Ignite and Velocity plans, BYOK allows you to connect your existing Cloudflare or AWS CloudFront (Coming Soon) account directly to SmallPict.

• SmallPict handles all the heavy lifting of image optimization and transformation.
• Your own CDN provider handles the edge caching and bandwidth billing.
• This gives you complete control over your domain routing, WAF rules, and caching headers.

To set up BYOK, navigate to CDN Setup in your Dashboard, select your provider, and input your API token (for Cloudflare, ensure you grant Zone.Cache Purge and Zone.Zone Settings: Read permissions).

Managed CDN

Available on the Momentum plan, SmallPict provisions and manages a global edge network for you.

• Zero configuration required.
• Bandwidth is included directly in your SmallPict subscription.
• Images are automatically cached and served from the nearest global point of presence.