> ## Documentation Index
> Fetch the complete documentation index at: https://docs.samsa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Image Operations

> Transform an existing image — img2img, variations, upscale, resize, background removal, and vectorization.

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:

| Operation              | Submit                                                                           | What it does                                        | Scope              |
| ---------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------- | ------------------ |
| **Img2img**            | [`POST /images/img2img`](/api-reference/image-ops/img2img)                       | Transform 1–14 reference images with a prompt       | `images.edit`      |
| **Variations**         | [`POST /images/variations`](/api-reference/image-ops/variations)                 | Generate creative variations of one image           | `images.transform` |
| **Upscale**            | [`POST /images/upscales`](/api-reference/image-ops/upscale)                      | Upscale one image to a higher resolution            | `images.transform` |
| **Resize**             | [`POST /images/resizes`](/api-reference/image-ops/resize)                        | Resize to a new aspect ratio (server-side outpaint) | `images.transform` |
| **Background removal** | [`POST /images/background-removals`](/api-reference/image-ops/remove-background) | Remove the background (transparent PNG)             | `images.transform` |
| **Vectorization**      | [`POST /images/vectorizations`](/api-reference/image-ops/vectorize)              | Vectorize one image to SVG                          | `images.transform` |

## 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](/guides/webhooks)).

<Note>
  **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.
</Note>

## 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`](/guides/errors#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`](/guides/errors#insufficient_credits), or the team-aware
[`insufficient_team_credits`](/guides/errors#insufficient_team_credits) /
[`insufficient_unallocated_credits`](/guides/errors#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](/guides/pricing) and
[`GET /credits`](/api-reference/account/credits).