SDKs

imagestep on npm and imagestep on PyPI are the REST API with the plumbing written once: the response envelope unwrapped, an idempotency key on every write, retryable failures sent again, waiting and paging done for you. Both have the same resources with the same methods — camelCase in JavaScript, snake_case in Python. The top of this page is how a client behaves; below it, every method of every resource. The same API is also a CLI for the terminal and an MCP server for agents.

Install and make a first call

JavaScript runs on Node 20 or newer, Deno, Bun and edge runtimes, ships ESM and CommonJS with its types, and has no runtime dependencies: it uses the runtime's own fetch and the global crypto. Python needs 3.10 or newer and one runtime dependency, httpx.

pnpm add imagestep     # JavaScript — or: npm install imagestep
pip install imagestep  # Python

Upload a photo, cut out its background as a job, and publish the result — four calls, each of which waits for what the next one needs:

import { ImageStep } from "imagestep";

const client = new ImageStep({ apiKey: process.env.IMAGESTEP_API_KEY });

const asset = await client.assets.upload("./product.jpg");           // stage, PUT, finish, wait for ingest
const job = await client.ops.removeBg(asset.id, { wait: true });      // a job; wait holds on until it settles
const [cutout] = await client.jobs.outputs(job);                      // what it made: new assets, in item order
const [published] = await client.assets.publish(cutout.id);
console.log(published.publicUrl);

from imagestep import ImageStep

client = ImageStep()  # api_key from IMAGESTEP_API_KEY

asset = client.assets.upload("./product.jpg")
job = client.ops.remove_bg(asset["id"], wait=True)
[cutout] = client.jobs.outputs(job)
[published] = client.assets.publish(cutout["id"])
print(published["publicUrl"])

The client

Methods return what the API returns, unwrapped from its envelope: plain objects in JavaScript, typed by the package's index.d.ts; plain dicts in Python, typed as TypedDicts generated from the OpenAPI document, with the keys as they are on the wire (asset["publicUrl"]). Python's keyword arguments are snake_case and go out under their wire names; a dict you pass as a body (a preset, a template, a webhook patch) is sent as written, in the wire's camelCase. In JavaScript the methods whose signature lists a signal take an AbortSignal; Python has no equivalent.

Everything a program imports: ImageStep (also the default export), ImageStepError, JobFailedError, verifyWebhookSignature and constructWebhookEvent from imagestep on npm; ImageStep, AsyncImageStep, ImageStepError, JobFailedError, WebhookSignatureError, verify_webhook_signature, construct_webhook_event, Page, RequestResult and BinaryResult from imagestep on PyPI.

Python: a sync client and an async one

ImageStep and AsyncImageStep take the same arguments and have the same resources with the same method names. On the async client every resource method is awaited, images included, and the iterate… methods are async iterators (async for). Close them with close() or with, and aclose() or async with. The differences inside a resource: the async jobs.wait also accepts a coroutine as on_progress, webhooks.verify and webhooks.construct_event are plain functions on both clients — no network, nothing to await — and the async assets.upload reads a local file synchronously before it sends it.

from imagestep import AsyncImageStep

async with AsyncImageStep() as client:
    job = await client.ops.remove_bg(asset_ids, wait=True)
    outputs = await client.jobs.outputs(job)

Retries, timeouts and idempotency

Every call sends the key as Authorization: ApiKey … and unwraps the envelope, so a method returns the data. What happens when a call fails:

The contract behind these — the envelope, the error codes, what a replay answers, rate limits — is Errors, idempotency and limits.

Waiting and paging

Two things the SDKs do in a loop so that your code does not: hold on until work is finished, and walk a listing to its end.

Errors

Every failure the API answers is raised as ImageStepError, after the retries the SDK is allowed have run out. Branch on retryable, never on the status: the status cannot tell a rate limit from a quota. The closed set of codes and what each one means are Errors, idempotency and limits.

import { ImageStepError, JobFailedError } from "imagestep";

try {
  await client.ops.upscale(ids, { wait: true });
} catch (err) {
  // retryable: the SDK already retried, so come back later — after what the service asked for
  if (err instanceof ImageStepError && err.retryable) queueForLater(ids, err.retryAfter);
  else if (err instanceof JobFailedError) console.error(err.job.status, err.job.id);
  else throw err; // not retryable: fix what err.param names
}

from imagestep import ImageStepError, JobFailedError

try:
    client.ops.upscale(ids, wait=True)
except JobFailedError as err:
    print(err.job["status"], err.job["id"])
except ImageStepError as err:
    if not err.retryable:
        raise  # fix what err.param names
    # retryable: the SDK already retried, so come back later — after what the service asked for
    queue_for_later(ids, err.retry_after)

ops — the catalogue, and running an op as a job

An op is one atomic capability, and ops.list() is the catalogue: read it instead of hard-coding names, since a new op appears there without an SDK release. Running an op submits a job, which is what owns progress, cancellation, settlement and an asset id for the result. What each op does and takes is Ops.

One helper per op

Each helper is ops.run with the op name filled in, and returns what run returns; the options are the same. A deterministic op's helper takes the op's own parameters — the keys shown — before them. Every name below is on client.

const { items } = await client.assets.list({ collection: "shoot-01" });
const ids = items.map((a) => a.id);
const estimate = await client.ops.estimate("convert", { assetIds: ids, parameters: { format: "webp", quality: 80 } });
if (estimate.sufficientCredit) {
  const job = await client.ops.convert(ids, { format: "webp", quality: 80 }, { wait: { onProgress: (j) => console.log(j.status) } });
}

page = client.assets.list(collection="shoot-01")
ids = [a["id"] for a in page.items]
estimate = client.ops.estimate("convert", asset_ids=ids, parameters={"format": "webp", "quality": 80})
if estimate["sufficientCredit"]:
    job = client.ops.convert(ids, {"format": "webp", "quality": 80}, wait={"on_progress": print})

images — bytes in, bytes out, nothing stored

The synchronous face: for when you are holding an image and only want the result back. Deterministic ops and deterministic presets only — AI ops, batches and anything you want an asset id for are jobs. Which ops qualify is read from ops.list() once per client, never from a list in the SDK. The endpoints and their limits are Synchronous ops.

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

const small = await client.images.transform("resize", { file: "./photo.jpg", parameters: { width: 1200 } });
await writeFile("small.jpg", small);

const { bytes, contentType, width } = await client.images.transformResult(null, { file: "./photo.jpg", preset: "builtin-util-web-optimize" });

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

result = client.images.transform_result(None, file="./photo.jpg", preset="builtin-util-web-optimize")
print(result.content_type, result.width, result.height)

assets — upload, find, publish

An asset is an image stored in the account with a stable id. Upload bytes or hand the service URLs to fetch, put them in a collection, and publish the ones that need a permanent URL. The asset document and its filters are Assets.

jobs — follow, collect, cancel

A job is the handle for work the service promises to finish. ops.run and presets.run create them; this is where you follow one. The job document and its states are Jobs.

One read has no method: the totals by status and type, GET /api/v1/jobs/counts — the numbers beside the console's job filters, a table for a person to look at more than a step a program takes. Send it as a raw request, client.get("/api/v1/jobs/counts") in either SDK. A program that watches one status already has its total: meta.total of jobs.list with that status.

presets — saved steps, run by slug

A preset is a versioned list of steps saved once and run over assets as one job — including a chain with a model in it, where the image each step makes for the next is handed on and cleaned up for you, and the dry run prices every step before the first one runs. The same steps run once without a preset as jobs.submit({steps, assetIds}). Built-ins are read-only; start from one by reading it and creating your own. The step format is Presets.

templates — HTML and CSS to PNG

A render template is HTML and CSS with {{ var }} placeholders; images.render and the render_template op turn rows of data into PNGs. Templates are versioned: an update saves a new version and the previous one stays readable and renderable as id@version. What a template may contain is Templates.

webhooks — endpoints and signatures

Register an https:// endpoint and the service POSTs signed events to it when a job finishes. The events, the retry schedule and auto-disable are Webhooks.

The same two functions are exported at the top level, so a webhook handler needs no client: verifyWebhookSignature and constructWebhookEvent in JavaScript, verify_webhook_signature and construct_webhook_event in Python. Verify the body exactly as it arrived; parsed and re-serialised JSON has different bytes and never verifies.

import { constructWebhookEvent } from "imagestep";

export async function POST(request) {
  const raw = await request.text();                                   // the raw body, not request.json()
  let event;
  try {
    event = await constructWebhookEvent(raw, request.headers.get("ImageStep-Signature"), secret);
  } catch {
    return new Response("bad signature", { status: 400 });
  }
  if (event.type === "job.completed") await collect(event.data);      // an error here is a 500, and a retry
  return new Response(null, { status: 204 });
}

from imagestep import WebhookSignatureError, construct_webhook_event

def handle(raw_body: bytes, signature: str | None, secret: str) -> int:
    try:
        event = construct_webhook_event(raw_body, signature, secret)
    except WebhookSignatureError:
        return 400
    if event["type"] == "job.completed":
        collect(event["data"])
    return 204

agent — the operating contract, and reporting a gap

The rules an automation is expected to follow, and somewhere to say what ImageStep could not do instead of routing around it. More on For agents.

models — the model catalogue

usage — what a key has spent

Raw requests

For an endpoint you want to call directly, with the same headers, envelope handling, idempotency key and retries as every method above.