Image editing

Modifica, fai inpainting, componi e rimuovi sfondi dalle immagini usando le API sincrone di Venice

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.

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

​

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.

Per l’inpainting, usa /image/edit o /image/multi-edit. Il vecchio parametro inpaint su /image/generate è deprecato.

​

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:

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.

Python

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)

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);

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"
  }'

​

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:

{
  "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:

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.

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

---

​

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:

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:

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:

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
• Models API 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
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

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.

---

​

Workflow correlati

• Usa Generazione di immagini quando parti dal testo invece che da un’immagine esistente.
• Usa Modelli di immagini per confrontare famiglie di modelli di generazione, edit e miglioramento.
• Usa Image Edit API, Multi-Edit API e Background Remove API per i dettagli completi dello schema.