POST that submits a job plus a GET that polls
it:
Source image
Every operation takes its source the same three ways — supply exactly one mode per source:image_id— the id of an image the API key’s creator owns in Samsa, including a local file uploaded first; any other id, including the id of an image another member of your organization created, returns404.url— anhttpsURL the server downloads under its SSRF guard.base64+mime_type— inline bytes,mime_typeone ofimage/jpeg,image/png,image/webp.
422. Img2img accepts an images array (1–14
sources); the other five take a single image object.
Asynchronous pattern
Every submit returns202 Accepted with a job handle
{ "id", "status": "pending", "estimated_credits" }. Poll the operation’s
GET .../{id} endpoint until status is completed (or failed/cancelled),
then read the result — each produced asset carries a presigned url valid for
24 hours. An img2img, variations, or resize job whose outputs all failed the
compliance pipeline ends failed with error delivery_blocked_compliance: <codes>;
a partly blocked job lists the withheld outputs in blocked_images (see
Compliance blocks). Pass a
webhook_url to be notified instead of polling (see Webhooks).
Cache hits (background removal & vectorization). When the source is an
image_id you own and a result already exists for it, the submit returns 202
with status: "completed" and estimated_credits: 0 immediately — no new job
is queued and your organization’s concurrency cap is not consumed. Every other
source (an https url, base64, or an owned image_id with no ready result)
is the normal charged, asynchronous path.
For vectorization, the result must come from the same engine and mode.Scopes
Img2img is an edit operation and requires theimages.edit scope. The other
five are transform operations and require images.transform. A key missing the
required scope receives 403 missing_scope.
Credits
Costs draw from the balance the calling credential can spend, not necessarily the organization’s whole pool; too little returns402 insufficient_credits, or the team-aware
insufficient_team_credits /
insufficient_unallocated_credits
in organizations with at least one active team (budget-exempt system organizations
stay on the generic code). An operational failure inside the deduction itself can
also surface as the generic insufficient_credits, whatever the regime. Each operation’s page states its cost
basis. See Pricing and
GET /credits.