Quickstart

Get a key

Sign in to the dashboard and create a key. A key starting smol_test_ works straight away on the sample files, at no cost. A key starting smol_live_ works on your own files once the account has a payment method.

Make a request

Send the file as the request body. The compressed file comes back as the response body. Nothing is stored on our side. With a test key, use the sample photo:

curl -O https://smolmac.com/api-samples/photo.jpg

The API is plain HTTPS, so curl is enough. The Node.js and Python tabs use the official SDKs, which add retries and typed results. Install one from this site:

npm install https://smolmac.com/sdk/smolmac-api-0.1.0.tgz
pip install https://smolmac.com/sdk/smol_api-0.1.0-py3-none-any.whl

Both are described under SDKs.

curl -X POST "https://api.smolmac.com/v1/compress" \
  -H "Authorization: Bearer $SMOL_API_KEY" \
  --data-binary @photo.jpg \
  -o photo.min.jpg

import { readFile, writeFile } from "node:fs/promises";
import { Smol } from "@smolmac/api";

const smol = new Smol({ apiKey: process.env.SMOL_API_KEY });

const out = await smol.compress(await readFile("photo.jpg"), { filename: "photo.jpg" });

await writeFile("photo.min.jpg", out.data);
console.log(out.result.savings_percent, "% smaller");

import os
from smol_api import Smol

smol = Smol(api_key=os.environ["SMOL_API_KEY"])

with open("photo.jpg", "rb") as f:
    out = smol.compress(f.read(), filename="photo.jpg")

with open("photo.min.jpg", "wb") as f:
    f.write(out.data)
print(out.result["savings_percent"], "% smaller")

The SDK pages list every method: TypeScript and Node.js, Python.

Read the result

The response headers say what happened. These are from a 1.6 MB JPEG sent with a live key:

HTTP/1.1 200 OK
Content-Type: image/jpeg
Smol-Original-Size: 1614027
Smol-Output-Size: 371580
Smol-Savings-Percent: 77.0
Smol-Output-Format: jpg
Smol-Kept-Original: false
Smol-Billed: true
Smol-Request-Id: req_nawnA3JOXOxTy0iq0T57

The SDKs read the same values for you: the result object is out.result, and out.billed says whether the request was charged. With a test key Smol-Billed is always false.

If the file cannot be made smaller, you get the original back with Smol-Kept-Original: true, and the request is free. Quote the Smol-Request-Id if you ever need to ask us about a request.

Choose a format

Options go in the query string. This converts the same photo to AVIF at quality 60 and fits it within a box 1200 pixels wide:

curl -X POST "https://api.smolmac.com/v1/compress?image.format=avif&image.quality=60&image.resize.width=1200" \
  -H "Authorization: Bearer $SMOL_API_KEY" \
  --data-binary @photo.jpg \
  -o photo.avif

const out = await smol.compress(await readFile("photo.jpg"), {
  filename: "photo.jpg",
  image: { format: "avif", quality: 60, resize: { width: 1200 } },
});
await writeFile("photo.avif", out.data);

with open("photo.jpg", "rb") as f:
    out = smol.compress(
        f.read(),
        {"image": {"format": "avif", "quality": 60, "resize": {"width": 1200}}},
        filename="photo.jpg",
    )

with open("photo.avif", "wb") as f:
    f.write(out.data)

Without options the API uses the same defaults as the Smol Mac app: keep the format, quality 75, fit within 2000 by 2000 pixels, and remove metadata. Every option is listed in Options.

Next steps

• Large files and jobs: upload, start a job, get a webhook.
• TypeScript SDK and Python SDK: the same API with retries, uploads in parts and webhook verification built in.
• Errors: every error code and what to do about it.
• How files are handled: what is kept, for how long, and how to verify it.