Vai al contenuto principale
Carica un file immagine locale su Samsa e ottieni un image_id. Usa l’image_id come immagine sorgente di un Magic Edit, img2img, variazioni, resize, upscale, rimozione dello sfondo, vettorizzazione o di una generazione image-to-video. Il MCP server offre lo stesso flusso come due strumenti, prepare_image_upload e complete_image_upload — vedi Strumenti MCP. Gli upload sono gratuiti — non costano credits.

​
I tre passaggi

1

Prepara

Chiama POST /images/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 entro un’ora. Samsa verifica il file e restituisce l’immagine con width e height misurate. Da quel momento l’image_id è utilizzabile.
curl --data-binary @file invia la lunghezza reale del file, quindi corrisponde sempre a size_bytes se hai misurato lo stesso file.

​
Limiti

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