Image Editing | Venice API Docs

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.

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)

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 "[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
`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.

​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

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

Formati di input supportati

Modelli e prezzi

Errori

Workflow correlati