Skip to main content
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:

image_id

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.

url

A public https URL the server downloads under its SSRF guard. See URL fetching below.

base64

Inline image bytes, sent as base64 together with a mime_type.
Provide one and only one per source. Sending none, or more than one, is a 422 validation_error.
Source examples

​
Size and format limits

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 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:
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 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:
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 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

Pricing

What each operation costs, including the per-op table.

MCP server

The same operations as tools — with the id/url-only source rule.

Errors

The error envelope and every code, including validation_error.

Image operations

The six operations and their full request/response contracts.