> ## 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 inputs

> How to supply source images to the API and MCP tools — by image_id, https URL, or base64 — with size, format, and URL-fetch rules.

Every operation that transforms an existing image — Magic Edit, img2img,
variations, resize, upscale, background removal, and vectorization — takes its
source image the same way. This page covers the three input modes, their limits,
and how the server fetches a URL.

## The three source modes

Over REST, each source image is **exactly one** of the following:

<CardGroup cols={3}>
  <Card title="image_id" icon="database">
    An image the **API key's creator** generated, edited, or uploaded in Samsa. No
    upload needed; the server reads it by id. Another member's image is not readable
    by your key.
  </Card>

  <Card title="url" icon="link">
    A public **`https`** URL the server downloads under its SSRF guard. See
    [URL fetching](#url-fetching) below.
  </Card>

  <Card title="base64" icon="file-code">
    Inline image bytes, sent as `base64` together with a `mime_type`.
  </Card>
</CardGroup>

Provide **one and only one** per source. Sending none, or more than one, is a
[`422 validation_error`](/guides/errors#validation_error).

```json Source examples theme={null}
// by id
{ "image_id": "8f3c…" }

// by URL
{ "url": "https://example.com/photo.jpg" }

// inline base64
{ "base64": "iVBORw0KGgo…", "mime_type": "image/png" }
```

## Size and format limits

| Rule                            | Value                                             |
| ------------------------------- | ------------------------------------------------- |
| Max size per source             | **10 MB** (decoded bytes)                         |
| Max source pixels (resize only) | **33,554,432** (32 MP, width × height)            |
| Accepted formats                | `image/jpeg`, `image/png`, `image/webp`           |
| `mime_type` (base64)            | Required, and must be one of the accepted formats |

The 10 MB cap is on the **decoded** image. For a `base64` source the encoded string
is bounded first (a longer string necessarily decodes past the limit), then the
decoded bytes are checked. Bytes that are not a readable image are rejected as a
`422` before anything is charged.

The pixel cap is independent of the size cap: a highly compressed source can sit under
10 MB and still exceed 32 MP, in which case
[`POST /images/resizes`](/api-reference/image-ops/resize) returns `422` with
`param: image` before any rendering. This 33,554,432-pixel source-raster cap is specific
to resize.

## Multiple sources (img2img)

Most operations take a single source image. **Img2img** accepts **1–14** source
images in one request — pass them as the `images` array, and source order is
preserved:

```json theme={null}
{
  "prompt": "a watercolor collage",
  "images": [
    { "image_id": "8f3c…" },
    { "url": "https://example.com/ref-2.png" },
    { "base64": "iVBORw0KGgo…", "mime_type": "image/webp" }
  ],
  "resolution": "2K"
}
```

Each item follows the same one-of rule. A request with more sources than the engine
allows is a `422`.

## MCP: image\_id or image\_url only

The [MCP tools](/mcp-server) accept a source as **`image_id`** or **`image_url`**
only — there is **no `base64` input over MCP**. Fetch or reference the image by id or
public URL instead:

```json theme={null}
// MCP img2img item
{ "image_id": "8f3c…" }
// or
{ "image_url": "https://example.com/photo.jpg" }
```

This applies to every MCP tool that takes a source image: `edit_image`, `img2img`,
`create_variations`, `resize_image`, `upscale_image`, `remove_background`, and
`vectorize_image`.

## URL fetching

When you pass a `url` (REST) or `image_url` (MCP), the server downloads it under a
strict SSRF guard before using it:

* **`https` only, port 443 only.** Any other scheme or port is rejected.
* **Public addresses only.** The hostname is resolved and every resulting IP is
  checked; private, loopback, link-local, and shared/CGNAT ranges are refused.
* **Redirects are re-validated.** Auto-follow is off; up to **3** redirect hops are
  followed manually, and each hop is re-checked against the same guard.
* **Content-type allow-list.** Only `jpeg`, `png`, and `webp` responses are
  accepted, and the 10 MB size cap is enforced on the streamed bytes (a declared
  `Content-Length` is never trusted on its own).
* **Time budget.** A connect timeout of \~5 s and a soft overall wall-clock budget of
  **\~30 s** span the whole download, including redirects.

Any fetch that fails a guard is a [`422 validation_error`](/guides/errors#validation_error)
naming the offending field — never a server error. Host a source somewhere publicly
reachable over `https`, or send it as `base64` (REST) instead.

## See also

<CardGroup cols={2}>
  <Card title="Pricing" icon="credit-card" href="/guides/pricing">
    What each operation costs, including the per-op table.
  </Card>

  <Card title="MCP server" icon="plug" href="/mcp-server">
    The same operations as tools — with the id/url-only source rule.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/guides/errors">
    The error envelope and every code, including `validation_error`.
  </Card>

  <Card title="Image operations" icon="wand-magic-sparkles" href="/api-reference/image-ops/overview">
    The six operations and their full request/response contracts.
  </Card>
</CardGroup>