Skip to main content
Gli endpoint delle operazioni sulle immagini trasformano un’immagine che hai già — nessuna generazione dal solo prompt. Sei operazioni, ognuna un POST che invia un job più un GET che lo interroga:

​
Immagine sorgente

Ogni operazione prende la sua sorgente negli stessi tre modi — fornisci esattamente una modalità per sorgente:
  • image_id — l’id di un’immagine che appartiene al creatore della chiave in Samsa; qualsiasi altro id restituisce 404, incluso quello di un’immagine creata da un altro membro della tua organizzazione.
  • url — un URL https che il server scarica sotto la sua protezione SSRF.
  • base64 + mime_type — byte inline, mime_type uno tra image/jpeg, image/png, image/webp.
Zero o più di una modalità è un 422. Img2img accetta un array images (1–14 sorgenti); le altre cinque prendono un singolo oggetto image.

​
Pattern asincrono

Ogni invio restituisce 202 Accepted con un handle del job { "id", "status": "pending", "estimated_credits" }. Interroga l’endpoint GET .../{id} dell’operazione finché status non è completed (oppure failed/cancelled), poi leggi il risultato — ogni asset prodotto include un presigned url valido per 24 ore. Passa un webhook_url per essere notificato invece di interrogare (vedi Webhook).
Cache hit (rimozione dello sfondo & vettorizzazione). Quando la sorgente è un image_id che possiedi e per esso esiste già un risultato, l’invio restituisce immediatamente 202 con status: "completed" e estimated_credits: 0 — nessun nuovo job viene messo in coda e il limite di concorrenza della tua organizzazione non viene consumato. Ogni altra sorgente (un url https, base64 o un image_id posseduto senza risultato pronto) è il normale percorso asincrono addebitato.

​
Scope

Img2img è un’operazione di edit e richiede lo scope images.edit. Le altre cinque sono operazioni di transform e richiedono images.transform. Una chiave priva dello scope richiesto riceve 403 missing_scope.

​
Credits

I costi attingono dal saldo che la credenziale chiamante può spendere, non necessariamente dall’intero pool dell’organizzazione; se è insufficiente l’API restituisce 402 insufficient_credits o i codici legati ai team insufficient_team_credits / insufficient_unallocated_credits nelle organizzazioni con almeno un team attivo (le organizzazioni di sistema esenti dal budgeting per team restano sul codice generico). Un guasto operativo nella detrazione stessa può inoltre presentarsi come il generico insufficient_credits, qualunque sia il regime. La pagina di ogni operazione indica la sua base di costo. Vedi Prezzi e GET /credits.