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

# Caricamento di immagini

> Carica un file immagine locale per ottenere un image_id da usare come sorgente in modifiche, operazioni sulle immagini e image-to-video.

Carica un file immagine locale su Samsa e ottieni un **`image_id`**. Usa l'`image_id`
come immagine sorgente di un [Magic Edit](/it/api-reference/edits/create.md),
[img2img](/it/api-reference/image-ops/img2img.md),
[variazioni](/it/api-reference/image-ops/variations.md),
[resize](/it/api-reference/image-ops/resize.md),
[upscale](/it/api-reference/image-ops/upscale.md),
[rimozione dello sfondo](/it/api-reference/image-ops/remove-background.md),
[vettorizzazione](/it/api-reference/image-ops/vectorize.md) o di una
[generazione image-to-video](/it/api-reference/videos/generate.md). Il MCP server offre lo
stesso flusso come due strumenti, `prepare_image_upload` e `complete_image_upload` —
vedi [Strumenti MCP](/it/mcp-server/tools.md).

Gli upload sono **gratuiti** — non costano credits.

## I tre passaggi

**1. Prepara**

Chiama [`POST /images/uploads/prepare`](/it/api-reference/uploads/prepare) con il
`filename`, il `content_type` e la dimensione **esatta** del file in
`size_bytes`. La risposta ti dà l'`image_id` e un `upload_url` presigned.

**2. Fai il PUT del file**

Fai il `PUT` dei byte grezzi del file su `upload_url` con lo stesso
`Content-Type`. Non inviare un header `Authorization` a questo URL.

**3. Completa**

Chiama [`POST /images/uploads/{image_id}/complete`](/it/api-reference/uploads/complete)
entro un'ora. Samsa verifica il file e restituisce l'immagine con `width` e
`height` misurate. Da quel momento l'`image_id` è utilizzabile.

```bash theme={null}
# 1. Prepare: send the EXACT file size
curl -X POST https://api.samsa.ai/public/v1/images/uploads/prepare \
  -H "Authorization: Bearer $SAMSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"filename\": \"photo.png\", \"content_type\": \"image/png\", \"size_bytes\": $(wc -c < photo.png)}"
# -> {"image_id": "...", "upload_url": "https://...", "expires_at": "...", "max_bytes": 10485760, "allowed_content_types": [...]}

# 2. PUT the raw bytes (same Content-Type, no Authorization header)
curl -X PUT -H "Content-Type: image/png" --data-binary @photo.png "<upload_url>"

# 3. Complete within the hour
curl -X POST https://api.samsa.ai/public/v1/images/uploads/<image_id>/complete \
  -H "Authorization: Bearer $SAMSA_API_KEY"
# -> {"image_id": "...", "status": "completed", "filename": "photo.png", "content_type": "image/png", "size_bytes": 4718592, "width": 2048, "height": 1536}
```

`curl --data-binary @file` invia la lunghezza reale del file, quindi corrisponde
sempre a `size_bytes` se hai misurato lo stesso file.

## Limiti

| Regola | Valore |
| - | - |
| Formati accettati | `image/jpeg`, `image/png`, `image/webp` |
| Dimensione massima del file | **10 MB** (10,485,760 byte) |
| Pixel massimi | **32 MP** (33,554,432 pixel, larghezza × altezza) |
| `size_bytes` | Obbligatorio. La dimensione esatta del file — è firmata in `upload_url`, quindi un `PUT` di qualsiasi altra lunghezza viene rifiutato |
| Validità di `upload_url` | **1 ora** — chiama complete entro quell'ora |
| Upload in attesa di completamento | Al massimo **20** per utente ([`429 too_many_pending_uploads`](/it/guides/errors#too_many_pending_uploads) oltre) |

Il file deve essere nel formato dichiarato in `content_type`. `width` e `height`
sono indicazioni facoltative al prepare: Samsa le usa solo per rifiutare in anticipo
un'immagine oltre i 32 MP. Le dimensioni salvate vengono sempre misurate dai byte
caricati. Un upload mai completato viene scartato dopo la scadenza del suo URL.

## Ciclo di vita ed errori

* **Non utilizzabile prima di complete.** Finché complete non riesce, l'`image_id`
  restituisce [`404 not_found`](/it/guides/errors#not_found) ovunque.
* **Complete è idempotente.** Richiamarlo restituisce lo stesso risultato e non
  cambia nulla. Un `PUT` successivo sullo stesso `upload_url` non sostituisce
  un'immagine completata.
* **`422 validation_error`** — non c'è ancora un file, oppure il file è vuoto, ha
  una dimensione diversa da `size_bytes`, è troppo grande, non è leggibile, è in un
  altro formato o supera i 32 MP. Samsa scarta un file rifiutato: fai il `PUT` di un
  file valido sullo stesso `upload_url` finché è ancora valido, poi richiama
  complete.
* **`404 not_found`** — l'`image_id` è sconosciuto, scaduto, appartiene a un altro
  utente o non è stato creato da prepare.
* **[`409 upload_in_progress`](/it/guides/errors#upload_in_progress)** — un'altra
  chiamata complete per lo stesso upload è in corso. Riprova tra qualche secondo; se
  continua per minuti, prepara un nuovo upload.
* **[`429 too_many_pending_uploads`](/it/guides/errors#too_many_pending_uploads)** —
  hai 20 upload in attesa di completamento. Completali, oppure aspetta che quelli
  non completati scadano (vedi `Retry-After`).

## Scope e proprietà

Entrambi gli endpoint accettano una chiave con **uno qualsiasi** degli scope
`images.edit`, `images.transform` o `videos.generate` — gli scope delle operazioni
che prendono un `image_id` sorgente. Non esiste uno scope di upload separato, quindi
le chiavi esistenti funzionano. Una chiave senza nessuno dei tre riceve
[`403 missing_scope`](/it/guides/errors#missing_scope).

L'immagine caricata appartiene all'**utente chiamante** — il creatore della chiave
API, o l'utente di un token OAuth. Gli altri membri della tua organizzazione non
possono usare il suo `image_id`.

## Provenienza

Un'immagine caricata **non** viene contrassegnata come generata dall'IA: non l'ha
prodotta Samsa. Un'immagine che un'operazione Samsa produce da un upload è un output
modificato dall'IA e viene contrassegnata come ogni altra modifica — vedi
[Provenienza dei contenuti](/it/guides/content-provenance.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.