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 immagine. 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 (il limite varia in base al modello)	Compositing e modifiche multi-riferimento
`POST /image/background-remove`	Rimuove lo sfondo da un’immagine	Ritagli trasparenti per prodotti, ritratti e asset

Venice non offre un endpoint /images/edits compatibile con OpenAI, quindi le chiamate dell’SDK OpenAI come client.images.edit() restituiscono 404. Invia invece le modifiche a /image/edit.

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 condizionare l’edit con immagini di riferimento aggiuntive.
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": "firered-image-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 dell’immagine. Salvalo direttamente in un file. Il formato è PNG per gli edit a 1K e JPEG per gli edit a 2K e 4K, oppure PNG a qualsiasi risoluzione quando transparent_background è true. Imposta output_format su jpeg, png o webp per sceglierlo esplicitamente. Gli endpoint di edit non hanno il parametro response_format, quindi non possono restituire l’immagine come JSON base64. Se ti serve il base64, codifica tu stesso i byte della risposta.

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": "firered-image-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: "firered-image-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": "firered-image-edit",
    "prompt": "Colorize this black and white portrait naturally",
    "image": "https://example.com/portrait-bw.jpg"
  }'

Passo 2: Usa multi-edit con immagini di riferimento

/image/multi-edit accetta più immagini, e il limite è specifico per modello. 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, oppure 1 quando combineImages è false. 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:

combinare una composizione esistente con un’immagine di riferimento aggiuntiva
fornire al modello esempi dello stile, dell’oggetto o della texture da applicare
vincolare l’edit in modo più stretto di quanto possa fare un prompt su una singola immagine

Richiesta JSON:

{
  "modelId": "firered-image-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-reference.png"
  ]
}

Richiesta multipart:

curl https://api.venice.ai/api/v1/image/multi-edit \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -F "modelId=firered-image-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 dell’immagine e il formato di output segue le stesse regole.

/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 un’immagine di riferimento aggiuntiva che mostri il risultato desiderato, poi descrivi con precisione la modifica prevista nel prompt.

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

Se stai comunque generando o modificando l’immagine, puoi saltare questa seconda chiamata: /image/generate, /image/edit e /image/multi-edit accettano transparent_background: true sui modelli supportati e restituiscono direttamente il canale alfa. Consulta Immagini con sfondo trasparente per il confronto.

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	`firered-image-edit`	ID del modello di edit
`aspect_ratio`	string	No	default del modello	Rapporto d’aspetto di output per i modelli che lo supportano
`resolution`	string	No	`1K`	Livello di risoluzione dell’immagine di output, come `1K`, `2K` o `4K`. I valori supportati variano in base al modello
`output_format`	string	No	dedotto	`jpeg`, `png` o `webp`. Se omesso, PNG per gli edit a 1K e JPEG per gli edit a 2K e 4K, oppure PNG a qualsiasi risoluzione quando `transparent_background` è `true`
`enhance_prompt`	boolean	No	`false`	Analizza l’immagine di input e riscrive l’istruzione di edit prima dell’inferenza
`disable_prompt_optimization_thinking`	boolean	No	default del modello	Salta il passaggio di thinking per l’ottimizzazione del prompt del modello per una generazione più rapida. Supportato solo dai modelli con `supportsOptimizePromptThinking`; ignorato dagli altri
`safe_mode`	boolean	No	`true`	Sfoca il contenuto per adulti nel risultato modificato. Imposta su `false` per disattivare la sfocatura.
`transparent_background`	boolean	No	`false`	Restituisce l’edit con un vero canale alfa. Richiede un modello con `supportsTransparentBackground: true` e `output_format` `png` o `webp` (dedotto come PNG se omesso). Consulta Immagini con sfondo trasparente
`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 — vedi `model_spec.constraints.maxInputImages`
`prompt`	string	Sì	-	Istruzioni testuali su come combinare o modificare le immagini
`modelId`	string	No	`firered-image-edit`	ID del modello di edit
`resolution`	string	No	`1K`	Livello di risoluzione dell’immagine di output, come `1K`, `2K` o `4K`. I valori supportati variano in base al modello
`quality`	string	No	default del modello	`low`, `medium` o `high` sui modelli che elencano `qualities` in `model_spec.constraints`. Valori più alti possono aumentare il costo della richiesta
`output_format`	string	No	dedotto	`jpeg`, `png` o `webp`. Stesse regole di deduzione di `/image/edit`
`enhance_prompt`	boolean	No	`false`	Analizza le immagini di input e riscrive l’istruzione di edit prima dell’inferenza
`disable_prompt_optimization_thinking`	boolean	No	default del modello	Salta il passaggio di thinking per l’ottimizzazione del prompt del modello per una generazione più rapida. Supportato solo dai modelli con `supportsOptimizePromptThinking`; ignorato dagli altri
`safe_mode`	boolean	No	`true`	Sfoca il contenuto per adulti nel risultato modificato. Imposta su `false` per disattivare la sfocatura.
`transparent_background`	boolean	No	`false`	Restituisce il risultato composto con un vero canale alfa. Stesse regole su modello e formato di `/image/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

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

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, quindi invia safe_mode: false per ricevere l’output senza sfocatura:

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

L’output per adulti (NSFW) non sfocato è disponibile per tutti gli utenti dell’API. Non ti serve un abbonamento Pro, e l’impostazione del filtro per contenuti maturi nell’app Venice non influisce sulle richieste di immagini effettuate tramite l’API. Le policy di contenuto variano in base al modello di edit e si applicano 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/jpeg` o `image/webp`
`/image/multi-edit`	Stringhe base64 o URL	Upload di file	`image/png`, `image/jpeg` o `image/webp`
`/image/background-remove`	Stringa base64 o URL	Upload di file	`image/png`

Per gli endpoint di edit, le immagini devono essere almeno di 256×256 pixel e il numero totale di pixel non deve superare 33.177.600 (risoluzione 8K). I file caricati devono essere inferiori a 25MB.

Modelli e prezzi

Il modello di edit di default è firered-image-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
`413`	File troppo grande	Mantieni i file caricati sotto i 25 MB
`415`	Content type non valido (solo `/image/multi-edit`; gli altri endpoint restituiscono `400`)	Usa correttamente JSON o multipart form-data
`422`	Violazione della policy sui contenuti o immagine di input troppo grande	Modifica il prompt o riduci le dimensioni dell’immagine
`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. Le richieste che violano la policy del modello selezionato vengono rifiutate con 422.

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 con immagini di riferimento

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 con immagini di riferimento

​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 con immagini di riferimento

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