Skip to main content
The image-operation endpoints transform an image you already have — no prompt-only generation. Six operations, each a 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; any other id, including the id of an image another member of your organization created, returns 404.
  • url — an https URL the server downloads under its SSRF guard.
  • base64 + mime_type — inline bytes, mime_type one of image/jpeg, image/png, image/webp.
Zero or more than one mode is a 422. Img2img accepts an images array (1–14 sources); the other five take a single image object.

​
Asynchronous pattern

Every submit returns 202 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. 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.

​
Scopes

Img2img is an edit operation and requires the images.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 returns 402 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.