Compress

Endpoint

Compresses one file and returns the result as the response body. Nothing is stored. The endpoint accepts images, PDFs and audio. Video must be sent as a job with operation: "compress".

If the file cannot be made smaller, your input is returned, marked Smol-Kept-Original: true, and the request is free. See Kept original.

Request

Authenticate with Authorization: Bearer $SMOL_API_KEY. Send the file in one of two forms. The file can be up to 25 MB (26,214,400 bytes), or 10 MB with a test key.

Raw body

The request body is the bytes of the file. Options go in the query string. Give the file's name with ?filename= or with a Content-Disposition request header. If both are present, the query parameter is used.

POST /v1/compress?image.format=avif&filename=photo.jpg HTTP/1.1
Host: api.smolmac.com
Authorization: Bearer $SMOL_API_KEY
Content-Length: 1614027

<the bytes of the file>

• Any Content-Type other than multipart/form-data is treated as a raw body. The header's value is not used to detect the file type.
• Send a Content-Length header. It is required with a test key. With a live key a body without it is accepted and streamed.

Multipart form

Send multipart/form-data with these parts:

Options may also be given in the query string of a multipart request. Where an option appears in both places, the query string wins, field by field.

The file name

The name is optional for most files. It is used for two things: to tell apart formats that share a container or have no signature (see type detection), and to name the file that comes back. Only the last path component is used.

Options

In the query string, an option is written as its dotted path: ?image.quality=60. Booleans are true or false. Only the options for the kind of file you sent are used. The others are checked and then ignored, so the same options can be sent with any file. An unknown option is refused with invalid_options, and param names it.

The video options are described in Options. They have no effect on this endpoint.

Response

Status 200. The body is the compressed file. The details are in the headers.

Errors

An error has a JSON body in place of the file. See Errors for the format and for what to do about each code.

Examples

Convert a JPEG to AVIF at quality 60, no wider than 1200 pixels:

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

import { readFile, writeFile } from "node:fs/promises";

const query = new URLSearchParams({
  "image.format": "avif",
  "image.quality": "60",
  "image.resize.width": "1200",
  filename: "photo.jpg",
});

const response = await fetch(`https://api.smolmac.com/v1/compress?${query}`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SMOL_API_KEY}` },
  body: await readFile("photo.jpg"),
});
if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.code}: ${error.message}`);
}

const result = JSON.parse(response.headers.get("smol-result"));
await writeFile(`photo.${result.output_format}`, Buffer.from(await response.arrayBuffer()));
console.log(result.savings_percent, "% smaller, billed:", response.headers.get("smol-billed"));

import json, os
import requests

with open("photo.jpg", "rb") as f:
    response = requests.post(
        "https://api.smolmac.com/v1/compress",
        params={
            "image.format": "avif",
            "image.quality": 60,
            "image.resize.width": 1200,
            "filename": "photo.jpg",
        },
        headers={"Authorization": f"Bearer {os.environ['SMOL_API_KEY']}"},
        data=f.read(),
    )
if not response.ok:
    error = response.json()["error"]
    raise RuntimeError(f"{error['code']}: {error['message']}")

result = json.loads(response.headers["Smol-Result"])
with open(f"photo.{result['output_format']}", "wb") as out:
    out.write(response.content)
print(result["savings_percent"], "% smaller, billed:", response.headers["Smol-Billed"])

The same request as a multipart form, with the options as JSON:

curl -X POST "https://api.smolmac.com/v1/compress" \
  -H "Authorization: Bearer $SMOL_API_KEY" \
  -F "[email protected]" \
  -F 'options={"image":{"format":"avif","quality":60,"resize":{"width":1200}}}' \
  -o photo.avif

Compress a PDF with the smallest preset:

curl -X POST "https://api.smolmac.com/v1/compress?pdf.quality=tiny" \
  -H "Authorization: Bearer $SMOL_API_KEY" \
  --data-binary @report.pdf \
  -o report.min.pdf

Example response

HTTP/1.1 200 OK
Content-Type: image/avif
Content-Length: 188406
Content-Disposition: attachment; filename="photo.avif"; filename*=UTF-8''photo.avif
Cache-Control: no-store
Smol-Version: 2026-10-01
RateLimit-Limit: 40
RateLimit-Remaining: 39
RateLimit-Reset: 1
Smol-Request-Id: req_nawnA3JOXOxTy0iq0T57
Smol-Original-Size: 1614027
Smol-Output-Size: 188406
Smol-Savings-Percent: 88.3
Smol-Output-Format: avif
Smol-Kept-Original: false
Smol-Billed: true
Smol-Result: {"kind":"image","input_format":"jpg","output_format":"avif","original_size":1614027,"output_size":188406,"savings_percent":88.3,"kept_original":false,"increased":false,"width":1200,"height":800,"pages":null,"duration_seconds":null,"video_codec":null,"warnings":[]}

<the bytes of photo.avif>