> ## 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.
# Input immagine
> Come fornire immagini sorgente all'API e agli strumenti MCP — tramite image_id, URL https o base64 — con le regole su dimensione, formato e recupero degli URL.
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:
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.
Un URL **`https`** pubblico che il server scarica sotto la sua protezione SSRF.
Vedi [Recupero degli URL](#recupero-degli-url) qui sotto.
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`](/it/guides/errors#validation_error).
```json Esempi di sorgente theme={null}
// tramite id
{ "image_id": "8f3c…" }
// tramite URL
{ "url": "https://example.com/photo.jpg" }
// base64 inline
{ "base64": "iVBORw0KGgo…", "mime_type": "image/png" }
```
## Limiti di dimensione e formato
| Regola | Valore |
| ------------------------------------------ | ----------------------------------------------------- |
| Dimensione massima per sorgente | **10 MB** (byte decodificati) |
| Pixel massimi della sorgente (solo resize) | **33.554.432** (32 MP, larghezza × altezza) |
| Formati accettati | `image/jpeg`, `image/png`, `image/webp` |
| `mime_type` (base64) | Obbligatorio, e deve essere uno dei formati accettati |
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`](/it/api-reference/image-ops/resize) 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:
```json theme={null}
{
"prompt": "un collage ad acquerello",
"images": [
{ "image_id": "8f3c…" },
{ "url": "https://example.com/ref-2.png" },
{ "base64": "iVBORw0KGgo…", "mime_type": "image/webp" }
],
"resolution": "2K"
}
```
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](/it/mcp-server) 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:
```json theme={null}
// elemento img2img MCP
{ "image_id": "8f3c…" }
// oppure
{ "image_url": "https://example.com/photo.jpg" }
```
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`](/it/guides/errors#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
Quanto costa ogni operazione, inclusa la tabella per operazione.
Le stesse operazioni come strumenti — con la regola sorgente solo id/url.
L'envelope di errore e ogni codice, incluso `validation_error`.
Le sei operazioni e i loro contratti di richiesta/risposta completi.