> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Image editing

> Modifica, fai inpainting, componi input a strati e rimuovi sfondi dalle immagini usando le API sincrone di Venice image edit, multi-edit e background-remove.

L'editing di immagini su Venice è sincrono. Invia la tua immagine sorgente a `/image/edit` o `/image/multi-edit` e il risultato modificato torna nella stessa risposta come file PNG. Per i ritagli, `/image/background-remove` restituisce un PNG trasparente.

<Warning>
  Gli endpoint di image edit sono sperimentali e il comportamento specifico dei modelli può cambiare nel tempo.
</Warning>

## Endpoint

| Endpoint                        | Scopo                                       | Ideale per                                         |
| ------------------------------- | ------------------------------------------- | -------------------------------------------------- |
| `POST /image/edit`              | Modifica una singola immagine con un prompt | Modifiche generali e inpainting guidato da prompt  |
| `POST /image/multi-edit`        | Modifica usando 1-3 immagini a strati       | Modifiche più controllate con maschere o overlay   |
| `POST /image/background-remove` | Rimuove lo sfondo da un'immagine            | Ritagli trasparenti per prodotti, ritratti e asset |

## Quando usare quale endpoint

* Usa `/image/edit` quando hai una sola immagine sorgente e vuoi cambiarne, rimuoverne o ridisegnarne una parte con un prompt.
* Usa `/image/multi-edit` quando hai bisogno di un controllo aggiuntivo tramite maschere, overlay o layer di riferimento.
* Usa `/image/background-remove` quando vuoi solo un soggetto in primo piano pulito con trasparenza.

<Note>
  Per l'inpainting, usa `/image/edit` o `/image/multi-edit`. Il vecchio parametro `inpaint` su `/image/generate` è deprecato.
</Note>

## Passo 1: Modifica una singola immagine

L'edit di una singola immagine è il flusso di inpainting più semplice. Invia un'immagine più un breve prompt come "remove the sign", "change the sky to sunrise" o "replace the background with a studio backdrop".

**Richiesta:**

```bash theme={"system"}
POST https://api.venice.ai/api/v1/image/edit
Authorization: Bearer $VENICE_API_KEY
Content-Type: application/json

{
  "model": "qwen-edit",
  "prompt": "Replace the cloudy sky with a warm sunrise while preserving the buildings and canal",
  "image": "https://example.com/venice-canal.jpg"
}
```

**Risposta (200):**
Il corpo della risposta è dato binario raw `image/png`. Salvalo direttamente in un file.

<CodeGroup>
  ```python Python theme={"system"}
  import base64
  import os
  import requests

  with open("input.jpg", "rb") as f:
      image_base64 = base64.b64encode(f.read()).decode("utf-8")

  response = requests.post(
      "https://api.venice.ai/api/v1/image/edit",
      headers={
          "Authorization": f"Bearer {os.environ['VENICE_API_KEY']}",
          "Content-Type": "application/json",
      },
      json={
          "model": "qwen-edit",
          "prompt": "Remove the tourist crowd from the square and keep the architecture intact",
          "image": image_base64,
      },
  )

  with open("edited.png", "wb") as f:
      f.write(response.content)
  ```

  ```javascript Node.js theme={"system"}
  import fs from "fs";

  const imageBase64 = fs.readFileSync("input.jpg").toString("base64");

  const response = await fetch("https://api.venice.ai/api/v1/image/edit", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VENICE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "qwen-edit",
      prompt: "Remove the tourist crowd from the square and keep the architecture intact",
      image: imageBase64,
    }),
  });

  const editedImage = Buffer.from(await response.arrayBuffer());
  fs.writeFileSync("edited.png", editedImage);
  ```

  ```bash cURL theme={"system"}
  curl https://api.venice.ai/api/v1/image/edit \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -H "Content-Type: application/json" \
    -o edited.png \
    -d '{
      "model": "qwen-edit",
      "prompt": "Colorize this black and white portrait naturally",
      "image": "https://example.com/portrait-bw.jpg"
    }'
  ```
</CodeGroup>

## Passo 2: Usa multi-edit per maschere o inpainting a strati

`/image/multi-edit` accetta fino a tre immagini. La prima immagine è quella di base. Le immagini rimanenti sono trattate come layer di edit o maschere, il che ti dà più controllo rispetto all'editing solo con prompt.

Questa è la scelta migliore quando vuoi:

* mirare a una regione specifica con una maschera
* combinare una composizione esistente con un overlay
* vincolare l'edit in modo più stretto di quanto possa fare un prompt su una singola immagine

**Richiesta JSON:**

```json theme={"system"}
{
  "modelId": "qwen-edit",
  "prompt": "Replace the blank billboard area with a glowing Venice film festival poster while preserving lighting and perspective",
  "images": [
    "https://example.com/street-scene.png",
    "https://example.com/billboard-mask.png"
  ]
}
```

**Richiesta multipart:**

```bash theme={"system"}
curl https://api.venice.ai/api/v1/image/multi-edit \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -F "modelId=qwen-edit" \
  -F "prompt=Replace the blank billboard area with a glowing Venice film festival poster while preserving lighting and perspective" \
  -F "images=@street-scene.png" \
  -F "images=@billboard-mask.png" \
  -o multi-edited.png
```

Come per `/image/edit`, il corpo della risposta è dato raw `image/png`.

<Note>
  `/image/multi-edit` attualmente usa il campo `modelId` invece di `model` nello schema della richiesta.
</Note>

***

## Consigli per l'inpainting

L'inpainting basato su prompt funziona meglio quando l'istruzione è breve e locale:

* `remove the tree`
* `change the sky to sunset`
* `replace the logo with a blank sign`
* `restore the torn corner of the photo`

Per cambiamenti di scena più ampi, descrivi cosa deve restare invariato:

```text theme={"system"}
Replace the background with a modern photo studio backdrop while preserving the subject pose, facial features, and clothing.
```

Se l'edit continua a interessare l'area sbagliata, passa da `/image/edit` a `/image/multi-edit` e fornisci una maschera o un layer di overlay.

***

## Passo 3: Rimuovi lo sfondo

Usa `/image/background-remove` quando vuoi isolare il soggetto in primo piano su uno sfondo trasparente. Questo endpoint restituisce un PNG con trasparenza alpha.

**Usando un URL di immagine:**

```bash theme={"system"}
curl https://api.venice.ai/api/v1/image/background-remove \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -o cutout.png \
  -d '{
    "image_url": "https://example.com/product-photo.jpg"
  }'
```

**Usando l'upload di un file locale:**

```bash theme={"system"}
curl https://api.venice.ai/api/v1/image/background-remove \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -F "image=@product-photo.jpg" \
  -o cutout.png
```

Usa la rimozione dello sfondo per:

* foto prodotto ecommerce
* foto profilo e ritratti
* asset che intendi posizionare su un nuovo sfondo

***

## Parametri della richiesta

### `/image/edit`

| Parametro      | Tipo                       | Obbligatorio | Default             | Descrizione                                                  |
| -------------- | -------------------------- | ------------ | ------------------- | ------------------------------------------------------------ |
| `image`        | file, stringa base64 o URL | Sì           | -                   | Immagine sorgente da modificare                              |
| `prompt`       | string                     | Sì           | -                   | Istruzioni testuali per l'edit                               |
| `model`        | string                     | No           | `qwen-edit`         | ID del modello di edit                                       |
| `aspect_ratio` | string                     | No           | default del modello | Rapporto d'aspetto di output per i modelli che lo supportano |
| `modelId`      | string                     | Deprecato    | -                   | Alias deprecato per `model`                                  |

### `/image/multi-edit`

| Parametro | Tipo                                     | Obbligatorio | Default     | Descrizione                                                                |
| --------- | ---------------------------------------- | ------------ | ----------- | -------------------------------------------------------------------------- |
| `images`  | array di 1-3 file, stringhe base64 o URL | Sì           | -           | La prima immagine è quella di base; le altre sono layer di edit o maschere |
| `prompt`  | string                                   | Sì           | -           | Istruzioni testuali su come combinare o modificare i layer                 |
| `modelId` | string                                   | No           | `qwen-edit` | ID del modello di edit                                                     |

### `/image/background-remove`

| Parametro   | Tipo                  | Obbligatorio                  | Descrizione                              |
| ----------- | --------------------- | ----------------------------- | ---------------------------------------- |
| `image`     | file o stringa base64 | Uno tra `image` o `image_url` | Immagine sorgente da ritagliare          |
| `image_url` | string                | Uno tra `image` o `image_url` | URL pubblico dell'immagine da ritagliare |

***

## Formati di input supportati

| Endpoint                   | Input JSON            | Input multipart | Output      |
| -------------------------- | --------------------- | --------------- | ----------- |
| `/image/edit`              | Stringa base64 o URL  | Upload di file  | `image/png` |
| `/image/multi-edit`        | Stringhe base64 o URL | Upload di file  | `image/png` |
| `/image/background-remove` | Stringa base64 o URL  | Upload di file  | `image/png` |

Per gli endpoint di edit, le dimensioni dell'immagine devono essere almeno `65536` pixel e non più di `33177600` pixel. I file caricati devono essere inferiori a `25MB`.

***

## Modelli e prezzi

Il modello di edit di default è `qwen-edit`, con un prezzo di **\$0,04 per edit**. Altri modelli con capacità di edit possono avere prezzi e vincoli diversi.

Vedi:

* [Prezzi delle immagini](/overview/pricing)
* [Models API](/api-reference/endpoint/models/list) con `type=inpaint`

***

## Errori

| Status | Significato                                | Azione                                                                       |
| ------ | ------------------------------------------ | ---------------------------------------------------------------------------- |
| `400`  | Parametri di richiesta non validi          | Controlla numero di immagini, nomi dei campi e formato di input              |
| `401`  | Autenticazione fallita                     | Controlla la tua API key                                                     |
| `402`  | Saldo insufficiente                        | Aggiungi crediti su [venice.ai/settings/api](https://venice.ai/settings/api) |
| `415`  | Content type non valido                    | Usa correttamente JSON o multipart form-data                                 |
| `429`  | Rate limit superato o modello sovraccarico | Riprova con backoff; controlla l'header `Retry-After`                        |
| `500`  | Elaborazione dell'inferenza fallita        | Riprova la richiesta                                                         |
| `503`  | Modello al massimo della capacità          | Riprova dopo un breve ritardo                                                |

<Note>
  Alcuni modelli di edit hanno policy sui contenuti più rigide rispetto ai modelli di generazione di immagini. Per esempio, `qwen-edit` blocca richieste che riguardano contenuti sessualmente espliciti, minori sessualizzati o violenza nel mondo reale.
</Note>

***

## Workflow correlati

* Usa [Generazione di immagini](/guides/media/image-generation) quando parti dal testo invece che da un'immagine esistente.
* Usa [Modelli di immagini](/models/image) per confrontare famiglie di modelli di generazione, edit e miglioramento.
* Usa [Image Edit API](/api-reference/endpoint/image/edit), [Multi-Edit API](/api-reference/endpoint/image/multi-edit) e [Background Remove API](/api-reference/endpoint/image/background-remove) per i dettagli completi dello schema.