Image Editing

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 più immagini di riferimento (3, o fino a 6 sui modelli di fascia superiore)	Compositing e modifiche multi-riferimento
`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.

Imposta enhance_prompt: true su entrambi gli endpoint di edit per fare in modo che un enhancer vision-aware analizzi l’immagine o le immagini di input e riscriva la tua istruzione prima di eseguire la modifica. Vedi Prompt Enhancement per comportamento, prezzi e dettagli sugli header di risposta.

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.

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 più immagini, e il limite è specifico per modello: la maggior parte dei modelli di edit ne consente 3, mentre quelli di fascia superiore — tra cui gpt-image-2-edit, nano-banana-pro-edit, seedream-v5-pro-edit, flux-2-max-edit e wan-2-7-pro-edit — ne consentono fino a 6. Leggi model_spec.constraints.maxInputImages da GET /models?type=inpaint per ottenere il limite di un dato modello; quando il campo è assente il limite è 3. La prima immagine è quella di base. Le immagini rimanenti sono riferimenti aggiuntivi che condizionano l’edit.

L’endpoint pubblico non ha un canale per le maschere. Le immagini aggiuntive agiscono come riferimenti sull’intera immagine, non come mappe di regioni — non esiste un parametro mask, e inviarne uno restituisce un 400. Scrivi prompt precisi per delimitare dove ricade l’edit.

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 "[email protected]" \
  -F "[email protected]" \
  -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 "[email protected]" \
  -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
`enhance_prompt`	boolean	No	`false`	Analizza l’immagine di input e riscrive l’istruzione di edit prima dell’inferenza
`safe_mode`	boolean	No	`true`	Sfoca il contenuto per adulti nel risultato modificato. Imposta su false per disattivare la sfocatura.
`modelId`	string	Deprecato	-	Alias deprecato per `model`

`/image/multi-edit`

Parametro	Tipo	Obbligatorio	Default	Descrizione
`images`	array di file, stringhe base64 o URL	Sì	-	La prima immagine è quella di base; le altre sono riferimenti aggiuntivi. Il massimo è specifico per modello — 3 per default, fino a 6 sui modelli di fascia superiore
`prompt`	string	Sì	-	Istruzioni testuali su come combinare o modificare i layer
`modelId`	string	No	`qwen-edit`	ID del modello di edit
`enhance_prompt`	boolean	No	`false`	Analizza le immagini di input e riscrive l’istruzione di edit prima dell’inferenza
`safe_mode`	boolean	No	`true`	Sfoca il contenuto per adulti nel risultato modificato. Imposta su false per disattivare la sfocatura.

`/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

/image/background-remove usa un modello interno fisso. Non accetta un campo model. Inviarne uno (per esempio "model": "bria-bg-remover") restituisce 400 invalid model id.

Contenuti per adulti e safe mode

Sia /image/edit che /image/multi-edit accettano safe_mode (default: true). Quando è abilitato, i contenuti per adulti nell’output modificato vengono sfocati. Imposta safe_mode: false per ricevere l’output senza sfocatura:

{
  "model": "qwen-edit-uncensored",
  "prompt": "…",
  "image": "…",
  "safe_mode": false
}

Il modello di default qwen-edit blocca comunque le immagini sessuali esplicite e la violenza nel mondo reale indipendentemente da safe_mode. Per l’editing non censurato, usa qwen-edit-uncensored. La differenza nel nome del parametro di moderazione tra gli endpoint spesso trae in inganno:

Endpoint	Campo per disattivare la sfocatura
`POST /image/edit`, `POST /image/multi-edit`	`safe_mode: false`
`POST /image/generate` (generazione nativa)	`safe_mode: false`
`POST /images/generations` (generazione compatibile con OpenAI)	`moderation: "low"`

Passare safe_mode a /images/generations restituisce 400 con Unrecognized key(s) in object: 'safe_mode'.

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. Il prompt enhancement aggiunge **$ 0,04 per riscrittura applicata al prezzo dell’edit. 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 Prompt Enhancement per capire come funziona la riscrittura degli edit basata sulla vision.
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.

Documentazione

Per iniziare

Testo e chat

Immagini

Video

Audio

Ricerca e RAG

Agenti e integrazioni

Strumenti di sviluppo

Strumenti per agenti

SDK e framework

Endpoint

Quando usare quale endpoint

Passo 1: Modifica una singola immagine

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

Consigli per l’inpainting

Passo 3: Rimuovi lo sfondo

Parametri della richiesta

`/image/edit`

`/image/multi-edit`

`/image/background-remove`

Contenuti per adulti e safe mode

Formati di input supportati

Modelli e prezzi

Errori

Workflow correlati

​Endpoint

​Quando usare quale endpoint

​Passo 1: Modifica una singola immagine

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

​Consigli per l’inpainting

​Passo 3: Rimuovi lo sfondo

​Parametri della richiesta

​/image/edit

​/image/multi-edit

​/image/background-remove

​Contenuti per adulti e safe mode

​Formati di input supportati

​Modelli e prezzi

​Errori

​Workflow correlati

Endpoint

Quando usare quale endpoint

Passo 1: Modifica una singola immagine

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

Consigli per l’inpainting

Passo 3: Rimuovi lo sfondo

Parametri della richiesta

`/image/edit`

`/image/multi-edit`

`/image/background-remove`

Contenuti per adulti e safe mode

Formati di input supportati

Modelli e prezzi

Errori

Workflow correlati