Genera immagini
Trasforma un prompt in immagini, componendo facoltativamente i modelli
style, object, person e setting addestrati dalla tua
organizzazione e le palette di colori.
Magic Edit
Modifica un’immagine esistente da un prompt — con o senza maschera — e riusa gli
stessi modelli addestrati per risultati fedeli al tuo brand.
Trasforma immagini
Esegui img2img, genera variazioni, ridimensiona per outpainting, fai l’upscale ad
alta risoluzione, rimuovi uno sfondo o vettorializza in SVG — uno strumento per
operazione.
Crea video
Produci video da un frame iniziale, da testo o da testo stilizzato con i tuoi
modelli addestrati — tutto come una singola chiamata a uno strumento.
Traccia job e credits
Interroga qualsiasi job fino al completamento e leggi il saldo credits rimanente
della tua organizzazione — le letture sono sempre gratuite.
Server URL — aggiungi questo unico endpoint a qualsiasi client MCP:
/mcp, senza barra finale) serve
entrambe le modalità di autenticazione. Il transport è stateless: ogni chiamata a uno
strumento restituisce una singola risposta JSON e gli strumenti di generazione
restituiscono un id del job immediatamente, così niente mantiene aperto uno stream di
lunga durata.
Connettiti in tre passaggi
1
Ottieni le tue credenziali
Le app interattive — Claude, ChatGPT e Microsoft Copilot (tramite
Copilot Studio) — accedono con OAuth; tu approvi una schermata di consenso
nell’app Samsa e non incolli mai una chiave. I client
headless — Claude Code, Cursor, n8n, SDK — usano una
API key creata in Settings → API Keys.
2
Aggiungi il server
Punta il tuo client a
https://api.samsa.ai/mcp. Non c’è nulla da installare né
alcun processo locale — consulta Collega il tuo client
per l’esatta configurazione una tantum.3
Inizia a creare
Il tuo client elenca i quindici strumenti Samsa. Chiedigli di generare
un’immagine, eseguire un Magic Edit, trasformare o fare l’upscale di un’immagine,
creare un video oppure creare e aggiornare i tuoi modelli addestrati — invia ogni
job e interroga quelli asincroni fino al completamento al posto tuo.
Autenticazione
L’endpoint MCP accetta due tipi di credenziali sullo stesso URL. Scegli quella che corrisponde al tuo client:
Entrambe agiscono per un’organizzazione: i credits vengono prelevati dal pool di
quell’organizzazione e gli asset generati appaiono nell’app sotto l’account connesso.
Consulta Autenticazione per capire come funzionano
chiavi, scope e organizzazioni.
L’accesso OAuth segue il flusso MCP standard: il client scopre il server di
autorizzazione di Samsa dal challenge
401, si registra dinamicamente (PKCE, nessun
client secret) e ti fa passare attraverso una schermata di consenso prima di
scambiare un access token di breve durata. Se un accesso non si completa, faccelo
sapere a support@samsa.ai.Il pattern asincrono
I nove strumenti multimediali che costano credits sono asincroni — accodano un job e restituiscono subito, così il tuo client non si blocca mai in attesa di un rendering.create_model è un decimo strumento di invio asincrono (interroga
get_job_status(kind="model", …)) ma è gratuito.
1
Invio
Chiama un qualsiasi strumento di invio —
generate_image, edit_image,
img2img, create_variations, resize_image, upscale_image,
remove_background, vectorize_image o generate_video. Restituisce
{ id, status: "pending", estimated_credits, next_step } in millisecondi e i
credits stimati vengono dedotti dal pool della tua organizzazione all’invio.2
Interrogazione
Chiama
get_job_status(kind=…, id=…) con l’id che hai ricevuto e il kind che lo
strumento di invio ha indicato. Lo stato passa da pending → processing →
completed (o failed). I job di immagine tipicamente finiscono da 30 secondi a
due minuti; i video da uno a cinque.3
Raccolta
Una volta
completed, la risposta contiene gli URL presigned del risultato validi
per 24 ore. Se un job termina failed per un problema di Samsa, i credits vengono
automaticamente rimborsati allo stesso pool.remove_background e vectorize_image sono memorizzati nella cache per immagine
sorgente: quando la sorgente è un image_id che possiedi e che ha già un
risultato, la chiamata salta la coda e restituisce subito
{ status: "completed", estimated_credits: 0 } — nessun credit e nessuno slot di
concorrenza consumato.Da leggere dopo
Strumenti
I quindici strumenti, i loro parametri, scope e costi.
Collega il tuo client
Configurazione una tantum per Claude, ChatGPT, Microsoft Copilot, Cursor, n8n e altri.
Risoluzione dei problemi
Sicurezza e credits, e come leggere una chiamata rifiutata.
Vedi anche
Autenticazione
Chiavi di organizzazione, scope e l’header Bearer.
Prezzi
Come vengono calcolati i credits per immagini, modifiche e video.
Rate limits
Rate per chiave, concorrenza per org e back-off.
Riferimento API
La superficie REST dietro gli stessi strumenti.