imagestep

The image step for your automations — one API key, one job handle, one stable URL. Generate, edit, remove backgrounds, upscale, convert and read metadata from Python 3.10+. One runtime dependency (httpx), a sync and an async client, typed (TypedDicts generated from the API's OpenAPI document).

import os
from imagestep import ImageStep

client = ImageStep(api_key=os.environ["IMAGESTEP_API_KEY"])

asset = client.assets.upload("./product.jpg")                     # stage → PUT → finish → ready
job = client.ops.remove_bg(asset["id"], wait=True)                # or any op: upscale, resize, convert, generate…
[cutout] = client.jobs.outputs(job)
[published] = client.assets.publish(cutout["id"])
print(published["publicUrl"])                                     # https://cdn.imagestep.dev/<id>

Only want the image back? One call, nothing stored:

small = client.images.transform("resize", file="./product.jpg", parameters={"width": 1200})
open("out.jpg", "wb").write(small)

# One op does one thing. Resize AND re-encode is two steps — save them as a preset and run it in one call:
webp = client.images.transform(None, file="./product.jpg", preset="web-optimize")
# your own render template, then a PNG from it (pin a version with f"{card['id']}@1")
card = client.templates.create({"name": "price-card", "html": "<h1>{{ title }}</h1>", "width": 1200, "height": 630})
png = client.images.render(card["id"], {"title": "Hello"})

Two paths, and the line between them is not speed — it is who carries the retry. ops.* gives you a job: this service promises to finish it, which is what buys progress, cancellation, webhooks and an asset_id. images.* runs while you wait and stores nothing, because you are still holding the input, so a failure costs you one re-send. AI ops and batches are always jobs.

Install

pip install imagestep

ImageStep() with no arguments reads IMAGESTEP_API_KEY (and IMAGESTEP_BASE_URL, default https://api.imagestep.dev). AsyncImageStep has the identical surface with every method awaitable — async with AsyncImageStep() as client: await client.ops.upscale(...), and that includes images.* (await client.images.transform("resize", file=…, parameters={"width": 1200})).

construct_webhook_event raises WebhookSignatureError when the signature does not check out; the JavaScript SDK throws a plain Error there, and takes its key as an argument rather than from the environment (it also runs on edge runtimes that have no process.env).

What you get

Pagination

Every list takes page (from 0) and per_page (100 by default and at most) and answers a Page — items plus meta (total, page, perPage, hasMore, nextCursor). Out of range is clamped, not refused, and meta reports the page actually served. Pass cursor=meta["nextCursor"] instead of a page number to read the rows after it: the service counts nothing then (no total, no page), and page 1 000 costs what page 1 did.

Don't write the loop — each listing has an iterator that walks to the end, following the nextCursor each answer carries:

for asset in client.assets.iterate(collection="shoot-01"):
    print(asset["id"])

assets.iterate · assets.iterate_collections · jobs.iterate · jobs.iterate_items(id) · templates.iterate · webhooks.iterate_deliveries(id) · agent.iterate_reports, on both clients (async for on AsyncImageStep). Pass cursor= (or page=) to resume a walk.

Every signature, parameter and return shape: https://imagestep.dev/docs/sdk — one reference for both SDKs, held against these sources by a test.