Python SDK

Install

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

• The package is served from this site. It is called smol-api and is imported as smol_api.
• If you call the API with Python's built-in urllib instead of this package, set a User-Agent header. The default one is refused with a 403 before the request reaches the API. This package and requests are not affected.
• It needs Python 3.9 or later. It uses only the standard library, so it installs nothing else.
• The client is synchronous. Each call returns when the API has answered.
• API keys are secrets. Use the package on a server, not in code you ship to users.

Create a client

import os
from smol_api import Smol

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

The package exports Smol, SmolError, FileResult and verify_webhook. Objects of the API, such as jobs, are returned as plain dictionaries with the field names the API uses.

Direct requests

For files of up to 25 MB. The file goes in and the result comes back in the same call. See Compress, Convert and Strip metadata.

with open("photo.jpg", "rb") as f:
    photo = f.read()

# Compress. Options are the same object as everywhere else in the API.
out = smol.compress(
    photo,
    {"image": {"format": "avif", "quality": 60, "resize": {"width": 1200}}},
    filename="photo.jpg",
)
with open(out.filename or "photo.avif", "wb") as f:
    f.write(out.data)
print(out.result["savings_percent"], out.billed)

# Convert to another format.
webp = smol.convert(photo, "webp", filename="photo.jpg")

# Remove metadata without re-encoding.
clean = smol.strip_metadata(photo, filename="photo.jpg")

file is the content of the file as bytes. Send filename when you have it: text formats such as CSV are recognised by their name, and the name is used for the result. Each method returns a FileResult:

A file that cannot be made smaller comes back unchanged, with result["kept_original"] true and billed false. See Kept original.

Jobs

For files over 25 MB, and for all video and office documents. run does the whole flow: it uploads the file, creates the job, waits for it and downloads the result.

with open("report.docx", "rb") as f:
    job, data = smol.run("convert", f.read(), filename="report.docx", options={"convert": {"to": "pdf"}})

with open("report.pdf", "wb") as f:
    f.write(data)
print(job["id"], job["result"]["output_size"])

• run returns a pair: the finished job object and the bytes of the result.
• If the job ends as failed or canceled, run raises a SmolError whose code is the error code of the job, such as encrypted_pdf. If the job is still running at the timeout, it raises TimeoutError. The job keeps running on our side.
• run has no parameters for output, webhook_url, metadata, retention_seconds or an idempotency key. Use the step-by-step calls for those.

Step by step

import uuid

# 1. Upload. Returns the upload id.
with open("scans.pdf", "rb") as f:
    upload_id = smol.upload(f.read(), "scans.pdf")

# 2. Create the job.
created = smol.create_job(
    {
        "operation": "compress",
        "input": {"upload": upload_id},
        "options": {"pdf": {"quality": "small"}},
        "retention_seconds": 600,
        "metadata": {"document_id": "doc_1234"},
    },
    idempotency_key=str(uuid.uuid4()),
)

# 3. Wait for a final status.
job = smol.wait_for_job(created["id"], timeout=600)
if job["status"] != "succeeded":
    raise RuntimeError(f"{job['error']['code']}: {job['error']['message']}")

# 4. Download, then delete the files on our side without waiting for them to expire.
data = smol.download(job)
smol.delete_job(job["id"])

An input can also be a URL: "input": {"url": "https://..."}. Nothing is uploaded then, and the job fetches the file itself.

Large files

upload(file, filename=None) sends a file of any size your plan allows and returns the upload id. Up to 95 MB it is one request. Above that the client splits the file into the parts the API asks for, sends them one after another, and completes the upload. run uses it, so run handles large files too.

with open("talk.mov", "rb") as f:
    upload_id = smol.upload(f.read(), "talk.mov")

job = smol.create_job({
    "operation": "compress",
    "input": {"upload": upload_id},
    "options": {"video": {"codec": "h264", "resolution": "1920"}},
    "webhook_url": "https://example.com/smol/webhook",
})

• The file is passed as bytes, so the whole file is in memory while it is sent. For a file too large for that, put it at an https URL and create the job with input.url.
• Each part is retried on its own, like any other request.

The four calls that upload is built from are public too:

Presets

A preset is a set of options saved on the account under a name.

smol.put_preset("web-hero", {"image": {"format": "avif", "quality": 60, "resize": {"width": 1600}}})

# On a direct request. Options sent with the request override the preset field by field.
hero = smol.compress(photo, preset="web-hero", filename="photo.jpg")
sharper = smol.compress(photo, {"image": {"quality": 80}}, preset="web-hero")

# On a job.
job, data = smol.run("compress", photo, filename="photo.jpg", preset="web-hero")

Usage

# The current month so far.
month = smol.usage()
print(month["totals"]["requests"], month["totals"]["amount_usd"])

# A range of days, in UTC. Both ends are included.
week = smol.usage(from_day="2026-10-01", to_day="2026-10-07")
for day in week["daily"]:
    print(day["day"], day["meters"])

A live key returns live usage and a test key test usage. The fields are described in Usage.

Estimate

estimate(operation, filename, size, options=None, **details) tells you what a request would cost and produce. No file is sent. details takes the other fields of POST /v1/estimate: duration_seconds, pages, width and height.

estimate = smol.estimate(
    "compress",
    "talk.mov",
    262_144_000,
    options={"video": {"codec": "h264"}},
    duration_seconds=150,  # needed for audio and video
    width=1920,
    height=1080,
)
print(estimate["lane"], estimate["meter"], estimate["quantity"], estimate["amount_usd"], estimate["notes"])

Webhooks

Verify a delivery

verify_webhook is a function of the module, not a method of the client. It checks the Smol-Signature header of a delivery and returns the parsed event. Pass the request body as bytes, exactly as it was received, before any JSON parsing.

import os

from flask import Flask, abort, request
from smol_api import verify_webhook

app = Flask(__name__)


@app.post("/smol/webhook")
def smol_webhook():
    try:
        event = verify_webhook(
            request.get_data(),
            request.headers.get("Smol-Signature"),
            os.environ["SMOL_WEBHOOK_SECRET"],
        )
    except ValueError:
        abort(400)

    if event["type"] == "job.succeeded":
        # Queue the work, then answer.
        print(event["data"]["job"]["id"], event["data"]["job"]["result"]["download_url"])
    return "", 204

• It raises ValueError if the header is missing or malformed, if the timestamp is outside the tolerance, or if the signature does not match.
• It returns every event type, the ping of a test included. A ping has an empty data, so check event["type"] before you read event["data"]["job"].

Manage endpoints

endpoint = smol.create_webhook_endpoint("https://example.com/smol/webhook")
print(endpoint["id"], endpoint["secret"])  # the secret is shown only here

# Send a signed ping and see what your endpoint answered.
test = smol.test_webhook_endpoint(endpoint["id"])
print(test["delivered"], test["status"], test["duration_ms"])

smol.update_webhook_endpoint(endpoint["id"], enabled=False)  # pause
smol.update_webhook_endpoint(endpoint["id"], enabled=True)  # resume

rotated = smol.rotate_webhook_secret(endpoint["id"])
print(rotated["secret"])  # the new secret, shown only here

Errors and retries

A response with an error status is raised as a SmolError. Its attributes come from the error object of the API.

from smol_api import SmolError

try:
    smol.compress(photo, {"image": {"quality": 120}})
except SmolError as error:
    print(error.status, error.code, error.param, error, error.request_id)

str(error) is the message of the error. The client retries by itself:

• What. A response with status 429, 500, 503 or 504, and a request that failed on the network before any answer came back (an OSError).
• How often. max_retries times, 2 by default, so a request is sent at most three times. Set max_retries=0 to turn retries off.
• How long it waits. The seconds in Retry-After when the response has the header. Otherwise a random time between half and the whole of a base that starts at half a second and doubles with each attempt, up to 8 seconds.
• What is raised in the end. The last SmolError. If every attempt failed on the network, the OSError of the last attempt.
• What is not retried. Every other status, including 409 idempotency_in_progress. Wait a second and call again yourself. The download in download is not retried either.

A retry of a direct request that did succeed, but whose answer was lost, is a second request and is billed as one. See Errors and retries.

Timeouts

A transport is a function that takes the method, the URL, the headers and the body, and returns the status, the response headers with lower-case names, and the response body. This one is the built-in transport with a timeout added:

import os
import urllib.error
import urllib.request

from smol_api import Smol


def transport(method, url, headers, body):
    request = urllib.request.Request(url, data=body, method=method, headers=headers)
    try:
        with urllib.request.urlopen(request, timeout=150) as response:
            return response.status, {k.lower(): v for k, v in response.headers.items()}, response.read()
    except urllib.error.HTTPError as error:
        return error.code, {k.lower(): v for k, v in error.headers.items()}, error.read()


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

• On our side a direct request is processed for at most 120 seconds, and then answers 504 timeout. Give your own timeout some room above that.
• A request cut off by your timeout raises an OSError, so it is retried like any network failure. A large upload needs a longer timeout than a small request.
• A job may run for up to 4 hours. When wait_for_job gives up, the job goes on. Call wait_for_job or get_job again later, or use a webhook.