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

# Operazioni sulle immagini

> Trasforma un'immagine esistente — img2img, variazioni, upscale, ridimensionamento, rimozione dello sfondo e vettorizzazione.

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:

| Operazione                 | Invia                                                                               | Cosa fa                                                    | Scope              |
| -------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------ |
| **Img2img**                | [`POST /images/img2img`](/it/api-reference/image-ops/img2img)                       | Trasforma 1–14 immagini di riferimento con un prompt       | `images.edit`      |
| **Variazioni**             | [`POST /images/variations`](/it/api-reference/image-ops/variations)                 | Genera variazioni creative di un'immagine                  | `images.transform` |
| **Upscale**                | [`POST /images/upscales`](/it/api-reference/image-ops/upscale)                      | Ingrandisce un'immagine a una risoluzione superiore        | `images.transform` |
| **Ridimensionamento**      | [`POST /images/resizes`](/it/api-reference/image-ops/resize)                        | Ridimensiona a un nuovo rapporto (outpainting lato server) | `images.transform` |
| **Rimozione dello sfondo** | [`POST /images/background-removals`](/it/api-reference/image-ops/remove-background) | Rimuove lo sfondo (PNG trasparente)                        | `images.transform` |
| **Vettorizzazione**        | [`POST /images/vectorizations`](/it/api-reference/image-ops/vectorize)              | Vettorizza un'immagine in SVG                              | `images.transform` |

## 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](/it/guides/webhooks)).

<Note>
  **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.
</Note>

## 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`](/it/guides/errors#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`](/it/guides/errors#insufficient_credits) o i
codici legati ai team
[`insufficient_team_credits`](/it/guides/errors#insufficient_team_credits) /
[`insufficient_unallocated_credits`](/it/guides/errors#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](/it/guides/pricing) e
[`GET /credits`](/it/api-reference/account/credits).