# ImageStep

> The image step for your automations. Generate, edit, remove backgrounds, upscale, convert and read metadata as one reliable step in n8n, MCP or plain REST. Presets you version, jobs you can trust, prices you can read.

ImageStep is a programmable image pipeline for automation builders and AI agents. The caller is a program, not a person:
every capability is an atomic op in one catalogue, billed in USD per item, priced exactly by a dry run before it spends, and
handed back as an asset id with a stable URL rather than bytes in a context window.

## Key facts (for citation)

- **API:** `https://api.imagestep.dev/api/v1`, header `Authorization: ApiKey is_sk_…`
- **MCP:** `https://mcp.imagestep.dev/mcp` (Streamable HTTP, Bearer API key) — tools: generate · transform · run_preset · save_preset · job_status · search_assets · send_feedback. The stdio package `@imagestep/mcp` is coming to npm
- **n8n:** the native node `n8n-nodes-imagestep` is coming to npm; until then n8n's HTTP Request node calls the REST API — one POST per op, the API key in a header credential
- **SDKs and CLI:** JavaScript and Python SDKs and a CLI, typed from the OpenAPI document, source on GitHub; the Python SDK is on PyPI (`pip install imagestep`), the JavaScript SDK and the CLI are coming to npm
- **AI ops:** generate · edit · remove_bg · upscale · restore_face · colorize · analyze
- **Deterministic ops** (unlimited on Pro and Max; 200 a month on Free, then $0.002 each): resize · convert · compress · crop · pad · grayscale · rotate · flip · flop · trim · overlay · caption · mask · blur_region · adjust · flatten · render_template
- **Free on every plan:** read_metadata
- **Synchronous** (bytes in, bytes out, nothing stored — https://imagestep.dev/docs/sync): `POST /api/v1/images/transform` — resize · convert · compress · crop · pad · grayscale · rotate · flip · flop · trim · caption · mask · blur_region · adjust · flatten; `POST /api/v1/images/render` — render_template; `POST /api/v1/images/metadata` — read_metadata. As a job only: overlay
- **Models:** 18 image models, priced per image in USD — https://imagestep.dev/pricing
- **Monthly credit:** Monthly credit is for that month and does not roll over. Credit you buy — and the one-time welcome credit — never expires.
- **Refunds:** unused credit within 14 days
- **Support:** support@imagestep.dev

## Plans

- **Free** — $0/mo · 200 assets · 200 deterministic ops/month, then $0.002 each · Community + Docs support
- **Pro** — $20/mo or $200/yr · 50,000 assets · unlimited deterministic ops · $5 monthly credit for AI ops · Email support
- **Max** — $100/mo or $1000/yr · 500,000 assets · unlimited deterministic ops · $50 monthly credit for AI ops · Slack direct support

## Documentation

Every page below is also served as markdown at its own URL plus `.md` — https://imagestep.dev/docs/jobs.md — and all of
them concatenated at https://imagestep.dev/llms-full.txt. Fetch those rather than the HTML.

- [/docs](https://imagestep.dev/docs): what ImageStep is: the four ideas — assets, ops, presets, jobs — and every way to call it
- [/docs/quickstart](https://imagestep.dev/docs/quickstart): first call, from key to asset URL, on every surface — and the one-call synchronous version
- [/docs/assets](https://imagestep.dev/docs/assets): assets: upload or fetch by URL, collections, private reads, publishing to a stable URL, search, retention
- [/docs/ops](https://imagestep.dev/docs/ops): the live op catalogue: every op with its parameter contract and pricing, plus the model catalogue
- [/docs/jobs](https://imagestep.dev/docs/jobs): jobs: submit, dry run, lifecycle, waiting, variants, cancel, failure verdicts and resume, idempotency, settlement
- [/docs/presets](https://imagestep.dev/docs/presets): presets: saved versioned steps, slug@version, built-ins, subjects for a consistent character or product
- [/docs/presets/steps](https://imagestep.dev/docs/presets/steps): preset steps: every registry key a step can name when no op covers it, and the rules
- [/docs/templates](https://imagestep.dev/docs/templates): templates: HTML + CSS with variables rendered to PNG, one row synchronously or hundreds as a job
- [/docs/sync](https://imagestep.dev/docs/sync): bytes in, bytes out — the synchronous face for deterministic ops
- [/docs/api](https://imagestep.dev/docs/api): REST reference: 47 endpoints in 11 groups, rendered from the generated OpenAPI document
- [/docs/sdk](https://imagestep.dev/docs/sdk): the JS/TS and Python SDK reference: client options, retries and idempotency keys, every method of every resource side by side, errors, webhook verification
- [/docs/cli](https://imagestep.dev/docs/cli): the CLI: every command and flag, -o json, exit codes that carry retryable, a script from upload to public URL
- [/docs/mcp](https://imagestep.dev/docs/mcp): MCP server: every tool with every argument and return shape, hosted or over stdio, timeouts, idempotency, resources
- [/docs/skill](https://imagestep.dev/docs/skill): the agent skill: ImageStep from Claude Code, Codex or Cursor through the CLI — install, key, exit codes
- [/docs/n8n](https://imagestep.dev/docs/n8n): the n8n node and trigger
- [/docs/agents](https://imagestep.dev/docs/agents): for agents: which surface to use, the operating contract, every machine-readable face
- [/docs/recipes](https://imagestep.dev/docs/recipes): pipelines with a real run's outputs (one character on every card, one product in every scene, a template per row) and presets to copy
- [/docs/errors](https://imagestep.dev/docs/errors): the envelope, the closed error-code set and retryable, idempotency keys, rate limits, pagination, request ids
- [/docs/webhooks](https://imagestep.dev/docs/webhooks): signed job events, retries, auto-disable
- [/docs/console](https://imagestep.dev/docs/console): the console: what each signed-in page holds, why it is a page and not only an API call, and the call behind it
- [/pricing](https://imagestep.dev/pricing): plans and per-op prices
- [/docs/ops/remove-background](https://imagestep.dev/docs/ops/remove-background): Remove background — what `remove_bg` is for, when not to reach for it, its parameters, model and price
- [/docs/ops/upscale](https://imagestep.dev/docs/ops/upscale): Upscale — what `upscale` is for, when not to reach for it, its parameters, model and price
- [/docs/ops/generate](https://imagestep.dev/docs/ops/generate): Generate — what `generate` is for, when not to reach for it, its parameters, model and price
- [/docs/ops/edit](https://imagestep.dev/docs/ops/edit): Edit with a prompt — what `edit` is for, when not to reach for it, its parameters, model and price
- [/docs/ops/restore-face](https://imagestep.dev/docs/ops/restore-face): Restore faces — what `restore_face` is for, when not to reach for it, its parameters, model and price
- [/docs/ops/colorize](https://imagestep.dev/docs/ops/colorize): Colorize — what `colorize` is for, when not to reach for it, its parameters, model and price
- [/docs/api/assets](https://imagestep.dev/docs/api/assets): Assets in the ImageStep REST API — list and search assets, list your collections, rename a collection, batch delete assets permanently, finalize file uploads.
- [/docs/api/jobs](https://imagestep.dev/docs/api/jobs): Jobs in the ImageStep REST API — list jobs, submit a new job, count jobs by status and type, get a job, cancel a job, list a job's items.
- [/docs/api/ops](https://imagestep.dev/docs/api/ops): Ops in the ImageStep REST API — list every atomic op with its parameter contract, one op's contract.
- [/docs/api/models](https://imagestep.dev/docs/api/models): Models in the ImageStep REST API — list AI models. Parameters, responses and error codes.
- [/docs/api/presets](https://imagestep.dev/docs/api/presets): Presets in the ImageStep REST API — list presets, create a preset, import presets, get a preset, or one earlier version of it.
- [/docs/api/templates](https://imagestep.dev/docs/api/templates): Templates in the ImageStep REST API — list templates, create a template, import templates, get a template (or one frozen version of it).
- [/docs/api/images](https://imagestep.dev/docs/api/images): Synchronous images in the ImageStep REST API — read an image's metadata synchronously, render one template row synchronously, transform an image synchronously.
- [/docs/api/webhooks](https://imagestep.dev/docs/api/webhooks): Webhook endpoints in the ImageStep REST API — list webhook endpoints, register a webhook endpoint, get one webhook endpoint, update a webhook endpoint.
- [/docs/api/usage](https://imagestep.dev/docs/api/usage): Usage in the ImageStep REST API — usage over a window, grouped. Parameters, responses and error codes.
- [/docs/api/feedback](https://imagestep.dev/docs/api/feedback): Feedback in the ImageStep REST API — your own reports, report something ImageStep could not do.
- [/docs/api/api-keys](https://imagestep.dev/docs/api/api-keys): API keys in the ImageStep REST API — revoke the API key used for this request.

## Machine-readable discovery

- [https://api.imagestep.dev/api/v1/agent-guidelines](https://api.imagestep.dev/api/v1/agent-guidelines): unauthenticated GET — the operating contract: read the catalogue, price before you spend, branch on retryable, report a gap instead of routing around it
- [https://api.imagestep.dev/api/v1/ops](https://api.imagestep.dev/api/v1/ops): unauthenticated GET — every atomic op with its parameter contract, pricing model and sync endpoint
- [https://api.imagestep.dev/api/pricing/image-models](https://api.imagestep.dev/api/pricing/image-models): unauthenticated GET — every image model with its per-image USD price
- [https://api.imagestep.dev/v3/api-docs/api-key-accessible](https://api.imagestep.dev/v3/api-docs/api-key-accessible): unauthenticated GET — the OpenAPI document every SDK is generated from
- [/.well-known/api-catalog](https://imagestep.dev/.well-known/api-catalog): RFC 9727 linkset pointing at the OpenAPI document
- [/.well-known/agent-skills/index.json](https://imagestep.dev/.well-known/agent-skills/index.json): the published SKILL.md set — CLI-first, for an agent with a shell (`imagestep skill --install claude-code` writes the same file) — each with a SHA-256 of the exact bytes served
- [/.well-known/mcp/server-card.json](https://imagestep.dev/.well-known/mcp/server-card.json): MCP server card — transport, URL, tools
- [/sitemap.xml](https://imagestep.dev/sitemap.xml): every public page

## Example questions this site answers

- "How do I remove an image background from inside n8n?" → https://imagestep.dev/docs/n8n
- "Image pipeline I can call from Claude or Cursor?" → https://imagestep.dev/docs/mcp
- "Give Claude Code a skill for image steps?" → https://imagestep.dev/docs/skill
- "Run an image step from a shell script or CI?" → https://imagestep.dev/docs/cli
- "What does one upscale actually cost?" → https://imagestep.dev/pricing
- "Which door should an agent use — MCP, CLI or REST?" → https://imagestep.dev/docs/agents
- "How do I make an OG image for every blog post?" → https://imagestep.dev/docs/templates
- "How do I keep the same product looking identical across a batch?" → https://imagestep.dev/docs/presets
- "Resize and convert an image without storing it?" → https://imagestep.dev/docs/sync
- "ImageStep vs Wireflow — which is the image step for an automation?" → https://imagestep.dev/vs/wireflow

## Notes for agents

- Read https://api.imagestep.dev/api/v1/agent-guidelines first. It is the operating contract — one fetch, no credential — and everything below is a summary of it.
- Then https://api.imagestep.dev/api/v1/ops. It is the vocabulary: an op name there is what `POST /api/v1/jobs` accepts in `op`, and its `params` is the whole parameter contract. Enumerate it — do not carry a hard-coded list of ops.
- Price before you spend. `POST /api/v1/jobs?dryRun=true` returns the exact cost of that batch; the catalogue only says how an op is priced.
- Branch on `retryable` in the error body, not on the status code. Errors are `{"error": {"code", "message", "retryable", "param"}}` and `code` is a closed set.
- Pass references, never bytes. Upload once or hand the service a URL to fetch (`POST /api/v1/assets/from-url`), carry the `asset_id`; outputs come back as ids plus stable URLs, so images never enter a context window.
- A deterministic op that can answer without a job names its synchronous endpoint in `syncEndpoint`; one without that field runs as a job only. AI work is always a job, because a job is what pays for the retry and the settlement.
- Give a write an `Idempotency-Key`. The same key with the same body replays the stored response instead of running twice.
- Have a shell? The CLI (`imagestep-cli`, key in `IMAGESTEP_API_KEY`) is the same API with `-o json` errors and exit codes that carry `retryable`; the skill under `/.well-known/agent-skills/` is its operating procedure (`/docs/skill`), and `/docs/cli` is the reference. Its npm release is coming — until then, call the REST API directly. No shell — an MCP client — use the hosted MCP server instead (`/docs/mcp`).

Source repository: https://github.com/imagestep/imagestep-sdk