comprestack

Official Python SDK for the Comprestack image optimization API.

Compress or convert images from scripts, Django, FastAPI, and workers with a small typed client. Same REST surface as the API docs and OpenAPI.

---

Install

pip install comprestack

Requirements: Python 3.9+ (uses httpx).

Create an API key in the dashboard, then set:

export COMPRESTACK_API_KEY=csk_live_…

Security

API keys must stay on the server. Do not put them in browsers, mobile apps, or public repositories.

---

Quick start

import os
from pathlib import Path

from comprestack import Comprestack

client = Comprestack(api_key=os.environ["COMPRESTACK_API_KEY"])

job = client.convert(
    ["photo.jpg"],
    format="webp",
    quality="balanced",
    maxWidth=1600,
)

Path("photo.webp").write_bytes(client.download(job))
print(f"Saved {job['files'][0]['saved_percent']}% · {job['usage']['remaining']} left")

Compress without changing format:

job = client.compress(["hero.png"], quality="high")

Use as a context manager to close the HTTP client:

with Comprestack(api_key=os.environ["COMPRESTACK_API_KEY"]) as client:
    job = client.compress([b"..."])

---

What you can do

Goal	Method
Shrink, keep format	compress(files, …)
Change format + shrink	convert(files, format=…, …)
Re-fetch job metadata	get_job(id)
Download ZIP / result	download(job) or download(download_url)
Download one file in a batch	download_file(job_id, index)
Check quota	usage()
White-label billing report	room_report(room_id)

Jobs finish in the same request. Results expire after about one hour.

---

Inputs

Input	Example
File path	"photo.jpg" or Path("photo.jpg")
Bytes	b"…", bytearray, memoryview
File object	open("photo.jpg", "rb")
Named bytes	("hero.png", data) or {"data": data, "filename": "hero.png"}

---

Options

Available on both compress and convert:

Option	Description
quality	"balanced" (default), "high", "smallest", or 1–100 on Pro/Business
format	convert only — webp, avif, jpeg, png, gif, tiff, bmp, ico
maxWidth / maxHeight	Downscale to fit (never enlarges)
target_kb	Aim for a max file size (Pro/Business)
lossless	Pixel-perfect where the codec allows (Pro/Business)
keep_metadata	Keep EXIF / color profile (default strips metadata, including GPS)

---

Client configuration

client = Comprestack(
    api_key=os.environ["COMPRESTACK_API_KEY"],
    # base_url="https://api.comprestack.com/api/v1",
    # timeout=300,
    # max_retries=2,  # extra tries on 429 / 503 (honours Retry-After)
    # on_progress=lambda e: print(e["phase"], e["path"], e["attempt"]),
    # headers={"X-Request-Id": "order-4417"},
)

---

Errors

Failed requests raise ComprestackError:

from comprestack import Comprestack, ComprestackError

try:
    client.compress(["huge.tiff"])
except ComprestackError as err:
    print(err.status, err.code, err.message)
    # err.retry_after — seconds, when the API sent Retry-After
    raise

Common codes: unauthorized, limit_reached, file_too_large, rate_limited, busy, plan_required.

---

Links

• API reference
• OpenAPI 3.1
• Dashboard — API keys
• TypeScript SDK
• Source

---

License

MIT © Comprestack