Skip to main content
Ogni operazione che trasforma un’immagine esistente — Magic Edit, img2img, variazioni, ridimensionamento, upscale, rimozione dello sfondo e vettorializzazione — riceve la sua immagine sorgente nello stesso modo. Questa pagina copre i tre modi di input, i loro limiti e come il server recupera un URL.

​
I tre modi di sorgente

Su REST, ogni immagine sorgente è esattamente una delle seguenti:

image_id

Un’immagine che il creatore della chiave ha generato, modificato o caricato in Samsa. Nessun caricamento necessario; il server la legge tramite id. L’immagine di un altro membro non è leggibile dalla tua chiave.

url

Un URL https pubblico che il server scarica sotto la sua protezione SSRF. Vedi Recupero degli URL qui sotto.

base64

Byte dell’immagine inline, inviati come base64 insieme a un mime_type.
Fornisci una e una sola per sorgente. Non inviarne nessuna, o più di una, è un 422 validation_error.
Esempi di sorgente

​
Limiti di dimensione e formato

Il limite di 10 MB riguarda l’immagine decodificata. Per una sorgente base64, la stringa codificata viene prima limitata (una stringa più lunga si decodifica necessariamente oltre il limite), poi i byte decodificati vengono verificati. Byte che non sono un’immagine leggibile vengono rifiutati come 422 prima di qualsiasi addebito. Il limite di pixel è indipendente da quello di dimensione: una sorgente molto compressa può restare sotto i 10 MB e superare comunque i 32 MP — in quel caso POST /images/resizes restituisce un 422 con param: image prima di qualsiasi rendering. Questo limite di 33.554.432 pixel per il raster sorgente è specifico del resize.

​
Sorgenti multiple (img2img)

La maggior parte delle operazioni prende una singola immagine sorgente. Img2img accetta 1–14 immagini sorgente in una richiesta — passale come array images, e l’ordine delle sorgenti è preservato:
Ogni elemento segue la stessa regola dell’unica scelta. Una richiesta con più sorgenti di quante ne consenta il motore è un 422.

​
MCP: solo image_id o image_url

Gli strumenti MCP accettano una sorgente solo come image_id o image_url — non c’è alcun input base64 su MCP. Referenzia invece l’immagine tramite id o URL pubblico:
Questo vale per ogni strumento MCP che prende un’immagine sorgente: edit_image, img2img, create_variations, resize_image, upscale_image, remove_background e vectorize_image.

​
Recupero degli URL

Quando passi un url (REST) o image_url (MCP), il server lo scarica sotto una rigorosa protezione SSRF prima di usarlo:
  • Solo https, solo porta 443. Qualsiasi altro schema o porta è rifiutato.
  • Solo indirizzi pubblici. Il nome host viene risolto e ogni IP risultante viene verificato; gli intervalli privati, loopback, link-local e condivisi/CGNAT sono rifiutati.
  • I redirect vengono rivalidati. L’auto-follow è disattivato; fino a 3 hop di redirect vengono seguiti manualmente, e ogni hop viene ricontrollato con la stessa protezione.
  • Allow-list dei content-type. Solo le risposte jpeg, png e webp sono accettate, e il limite di 10 MB viene applicato ai byte in streaming (un Content-Length dichiarato non viene mai creduto da solo).
  • Budget di tempo. Un timeout di connessione di ~5 s e un budget complessivo morbido di orologio da parete di ~30 s coprono l’intero download, inclusi i redirect.
Qualsiasi recupero che non supera una protezione è un 422 validation_error che nomina il campo incriminato — mai un errore del server. Ospita una sorgente da qualche parte raggiungibile pubblicamente via https, o inviala come base64 (REST).

​
Vedi anche

Prezzi

Quanto costa ogni operazione, inclusa la tabella per operazione.

Server MCP

Le stesse operazioni come strumenti — con la regola sorgente solo id/url.

Errori

L’envelope di errore e ogni codice, incluso validation_error.

Operazioni sulle immagini

Le sei operazioni e i loro contratti di richiesta/risposta completi.