Single image

One photo in, one result out, in one call. The shortcut for “I have an image, give me the cutout”.

POST/v1/images

Behind the scenes a one-photo batch is created and started for you, and the connection waits for it (up to timeout seconds, 60 by default). One credit; refunded like any other photo when the automatic check flags it. The batch stays on the server for two hours, so the same result can be fetched again through /v1/jobs/{jobId}.

A file

curl -X POST https://trycutstack.com/v1/images \
  -H "Authorization: Bearer $CUTSTACK_API_KEY" \
  -F "file=@chair.jpg" \
  -F 'settings={"presetId":"shopify","background":{"mode":"white"}}' \
  -F "format=webp" \
  -o chair.webp -D headers.txt

Form fields, all optional except file:

Field	Values	Meaning
`settings`	JSON	The same shape as a batch’s `defaults` (Settings).
`response`	`image` (default), `json`	The bytes, or a description with links.
`format`	`png`, `jpeg`, `webp`	Convert the image answer. Default: as rendered (PNG when transparent).
`optimize`	`marketplace` (default), `lossless`, `web`, `off`	How hard the file is squeezed.
`timeout`	5–60	Seconds to hold the connection.

A link

curl -X POST https://trycutstack.com/v1/images \
  -H "Authorization: Bearer $CUTSTACK_API_KEY" -H "Content-Type: application/json" \
  -d '{ "url": "https://cdn.example.com/p/chair.jpg", "response": "json" }'

{
  "jobId": "…", "itemId": "…", "status": "done",
  "charged": 1, "review": "none", "refunded": false,
  "fileUrl": "/v1/jobs/…/items/…/file?v=0",
  "statusUrl": "/v1/jobs/…?wait=60", "reviewUrl": "/v1/jobs/…/review",
  "item": { … the photo, as in a batch … }
}

The image answer’s headers

Header	Meaning
`X-Cutstack-Job-Id`, `X-Cutstack-Item-Id`	The batch and photo behind the result.
`X-Cutstack-Charged`	`1`, or `0` when the check flagged it and refunded you.
`X-Cutstack-Review`	`none` or `red`. With `red`, read `reviewUrl` for the reason.
`X-Cutstack-Score`	The automatic score, 0–100.

When it does not come back clean

Status	Meaning	Charged
`422 PROCESSING_FAILED`	The input’s fault: unreadable file, no subject found. `reason` carries the code.	0
`503 PROCESSING_FAILED`	Our side: the model was unavailable. Retry in a moment.	0
`202`	Still processing when `timeout` ran out. The JSON has the ids and links; poll `statusUrl`. The credit settles when the photo finishes.	settled later
`504 TIMEOUT`	The photo never started (the queue was busy for the whole timeout). The reservation was released.	0
`409 TOO_MANY_ACTIVE`	Each call is one running batch; the account allows two at once. Send fewer in parallel, or use a batch.	0

Idempotency-Key works here too. A replay answers as JSON whatever response said, with the same jobId.

Many photos? A batch is cheaper in requests and gives you the ZIP and the review queue in one place.

Next: Events and webhooks. Live progress, signed deliveries, retries.