Skip to main content
Jede Operation, die ein vorhandenes Bild transformiert — Magic Edit, img2img, Variationen, Resize, Upscale, Hintergrundentfernung und Vektorisierung — nimmt ihr Quellbild auf dieselbe Weise entgegen. Diese Seite behandelt die drei Eingabemodi, ihre Grenzen und wie der Server eine URL abruft.

​
Die drei Quellmodi

Über REST ist jedes Quellbild genau eines der folgenden:

image_id

Ein Bild, das der Key-Ersteller in Samsa generiert, bearbeitet oder hochgeladen hat. Kein Upload nötig; der Server liest es per id. Das Bild eines anderen Mitglieds ist für deinen Key nicht lesbar.

url

Eine öffentliche https-URL, die der Server unter seinem SSRF-Schutz herunterlädt. Siehe URL-Abruf unten.

base64

Inline-Bildbytes, gesendet als base64 zusammen mit einem mime_type.
Gib genau eines pro Quelle an. Keines oder mehrere zu senden ist ein 422 validation_error.
Quellbeispiele

​
Größen- und Formatgrenzen

Die 10-MB-Grenze gilt für das dekodierte Bild. Bei einer base64-Quelle wird zuerst die kodierte Zeichenkette begrenzt (eine längere Zeichenkette dekodiert zwangsläufig über die Grenze), danach werden die dekodierten Bytes geprüft. Bytes, die kein lesbares Bild sind, werden als 422 abgelehnt, bevor etwas berechnet wird. Die Pixelgrenze ist unabhängig von der Größengrenze: Eine stark komprimierte Quelle kann unter 10 MB bleiben und trotzdem 32 MP überschreiten — dann gibt POST /images/resizes ein 422 mit param: image zurück, bevor etwas gerendert wird. Diese Grenze von 33.554.432 Pixeln für das Quellraster gilt speziell für Resize.

​
Mehrere Quellen (img2img)

Die meisten Operationen nehmen ein einzelnes Quellbild. Img2img akzeptiert 1–14 Quellbilder in einer Anfrage — übergib sie als images-Array, und die Quellreihenfolge bleibt erhalten:
Jedes Element folgt derselben Genau-eines-Regel. Eine Anfrage mit mehr Quellen, als die Engine erlaubt, ist ein 422.

​
MCP: nur image_id oder image_url

Die MCP-Tools akzeptieren eine Quelle nur als image_id oder image_url — es gibt keine base64-Eingabe über MCP. Referenziere das Bild stattdessen per id oder öffentlicher URL:
Das gilt für jedes MCP-Tool, das ein Quellbild entgegennimmt: edit_image, img2img, create_variations, resize_image, upscale_image, remove_background und vectorize_image.

​
URL-Abruf

Wenn du eine url (REST) oder image_url (MCP) übergibst, lädt der Server sie unter einem strengen SSRF-Schutz herunter, bevor er sie verwendet:
  • Nur https, nur Port 443. Jedes andere Schema oder jeder andere Port wird abgelehnt.
  • Nur öffentliche Adressen. Der Hostname wird aufgelöst und jede resultierende IP geprüft; private, Loopback-, Link-local- und geteilte/CGNAT-Bereiche werden abgelehnt.
  • Redirects werden neu validiert. Auto-Follow ist aus; bis zu 3 Redirect-Hops werden manuell gefolgt, und jeder Hop wird erneut gegen denselben Schutz geprüft.
  • Content-Type-Allowlist. Nur jpeg-, png- und webp-Antworten werden akzeptiert, und die 10-MB-Grenze wird auf die gestreamten Bytes angewendet (ein angegebener Content-Length wird nie allein vertraut).
  • Zeitbudget. Ein Connect-Timeout von ~5 s und ein weiches Gesamt-Wall-Clock-Budget von ~30 s umspannen den gesamten Download inklusive Redirects.
Jeder Abruf, der einen Schutz nicht besteht, ist ein 422 validation_error, das das betroffene Feld nennt — nie ein Serverfehler. Hoste eine Quelle irgendwo öffentlich über https erreichbar, oder sende sie als base64 (REST).

​
Siehe auch

Preise

Was jede Operation kostet, inklusive der Tabelle pro Operation.

MCP-Server

Dieselben Operationen als Tools — mit der id/url-only-Quellregel.

Fehler

Der Fehler-Envelope und jeder Code, inklusive validation_error.

Bildoperationen

Die sechs Operationen und ihre vollständigen Request-/Response-Verträge.