Image Generation | Venice API Docs

La generazione di immagini su Venice è sincrona. Invia un prompt a /image/generate e ricevi la tua immagine nella stessa risposta, sia come base64 dentro un JSON sia come binario raw quando return_binary è true.

Endpoint

Endpoint	Scopo	Quando usarlo
`POST /image/generate`	API di generazione di immagini nativa di Venice	Usalo per il supporto completo delle funzionalità
`GET /image/styles`	Elenco dei preset di stile disponibili	Usalo prima di inviare `style_preset`
`POST /images/generations`	API di generazione di immagini compatibile con OpenAI	Usalo quando migri client di immagini OpenAI esistenti

Passo 1: Invia una richiesta di generazione

Il dimensionamento è specifico per ogni modello. Alcuni modelli accettano width e height espliciti; altri espongono aspect_ratio; e i modelli a tier di risoluzione espongono aspect_ratio più valori di resolution come 1K, 2K o 4K.

qwen-image, qwen-image-3, qwen-image-3-pro, qwen-image-2-1-turbo e qwen-image-2-1-pro non accettano più width o height. Inviarne uno restituisce 400 con “width and height are no longer supported for this model. Use aspect_ratio instead.” Verifica model_spec.constraints da GET /models?type=image prima di scegliere i campi di dimensionamento.

Esempio di dimensionamento basato su pixel:

POST https://api.venice.ai/api/v1/image/generate
Authorization: Bearer $VENICE_API_KEY
Content-Type: application/json

{
  "model": "venice-sd35",
  "prompt": "A cinematic photo of a gondola passing through a narrow Venice canal at blue hour, warm window lights reflecting on the water",
  "negative_prompt": "blurry, low quality, distorted anatomy, text, watermark",
  "width": 1024,
  "height": 1024,
  "format": "webp"
}

Esempio di dimensionamento basato su aspect ratio:

POST https://api.venice.ai/api/v1/image/generate
Authorization: Bearer $VENICE_API_KEY
Content-Type: application/json

{
  "model": "qwen-image-2",
  "prompt": "A cinematic photo of a gondola passing through a narrow Venice canal at blue hour",
  "aspect_ratio": "16:9",
  "format": "webp"
}

Esempio di dimensionamento basato su tier di risoluzione:

POST https://api.venice.ai/api/v1/image/generate
Authorization: Bearer $VENICE_API_KEY
Content-Type: application/json

{
  "model": "gpt-image-2",
  "prompt": "A cinematic wide shot of a gondola passing through a narrow Venice canal at blue hour",
  "aspect_ratio": "16:9",
  "resolution": "4K",
  "format": "png"
}

Lo stesso schema si applica ad altri modelli a tier di risoluzione:

{
  "model": "nano-banana-pro",
  "prompt": "A serene canal in Venice at sunset",
  "aspect_ratio": "16:9",
  "resolution": "2K"
}

Usa Modelli di immagini o l’API Models per confermare quali campi di dimensionamento accetta ciascun modello. Risposta (200):

{
  "id": "generate-image-1234567890",
  "images": [
    "UklGRiIAAABXRUJQVlA4IBYAAAAwAQCdASoQABAAPm..."
  ],
  "timing": {
    "inferenceDuration": 1840,
    "inferencePreprocessingTime": 22,
    "inferenceQueueTime": 31,
    "total": 1893
  }
}

L’array images contiene i dati dell’immagine codificati in base64. Decodifica il primo elemento per salvarlo o visualizzarlo. timing.total è la durata complessiva della richiesta in millisecondi.

Passo 2: Decodifica e salva l’immagine

import base64
import os
import requests

response = requests.post(
    "https://api.venice.ai/api/v1/image/generate",
    headers={
        "Authorization": f"Bearer {os.environ['VENICE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "venice-sd35",
        "prompt": "A cinematic photo of a gondola passing through a narrow Venice canal at blue hour, warm window lights reflecting on the water",
        "width": 1024,
        "height": 1024,
        "format": "webp",
    },
)

data = response.json()
image_bytes = base64.b64decode(data["images"][0])

with open("output.webp", "wb") as f:
    f.write(image_bytes)

print(f"Saved image from request {data['id']}")

import fs from "fs";

const response = await fetch("https://api.venice.ai/api/v1/image/generate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VENICE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "venice-sd35",
    prompt: "A cinematic photo of a gondola passing through a narrow Venice canal at blue hour, warm window lights reflecting on the water",
    width: 1024,
    height: 1024,
    format: "webp",
  }),
});

const data = await response.json();
const imageBuffer = Buffer.from(data.images[0], "base64");
fs.writeFileSync("output.webp", imageBuffer);

console.log(`Saved image from request ${data.id}`);

Passo 3: Restituire binario invece di JSON (opzionale)

Se vuoi che il corpo della risposta sia il file immagine stesso, imposta return_binary: true. Questo è utile quando vuoi fare streaming o salvare l’immagine direttamente senza decodifica base64.

curl https://api.venice.ai/api/v1/image/generate \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -o output.png \
  -d '{
    "model": "qwen-image-2",
    "prompt": "Minimalist poster of a moonlit Venetian bridge in deep blue tones",
    "format": "png",
    "return_binary": true
  }'

Quando return_binary è true, il corpo della risposta è dato raw image/jpeg, image/png o image/webp in base al format richiesto.

variants è supportato solo quando return_binary è false.

Passo 4: Elenca gli stili di immagine disponibili (opzionale)

Se vuoi usare style_preset, recupera prima gli stili disponibili da /image/styles:

curl https://api.venice.ai/api/v1/image/styles

Questo endpoint è pubblico e non richiede una API key. Risposta (200):

{
  "object": "list",
  "data": [
    "3D Model",
    "Analog Film",
    "Anime",
    "Cinematic",
    "Digital Art"
  ]
}

I nomi degli stili sono dentro data, non al livello superiore — leggi response.data invece di iterare direttamente sull’oggetto della risposta. Poi passa uno di questi valori nella tua richiesta di generazione:

{
  "model": "qwen-image-2",
  "prompt": "A futuristic Venice skyline at sunrise",
  "style_preset": "Cinematic"
}

Usa l’endpoint degli stili quando vuoi i nomi esatti dei preset invece di indovinarli.

Parametri della richiesta

Parametro	Tipo	Obbligatorio	Default	Descrizione
`model`	string	Sì	-	ID del modello da usare per la generazione
`prompt`	string	Sì	-	Cosa generare
`negative_prompt`	string	No	-	Cosa evitare nell’immagine
`width`	integer	No	`1024`	Larghezza di output in pixel per modelli pixel-based come `venice-sd35`. Rifiutato dalla famiglia Qwen Image — vedi la nota qui sotto
`height`	integer	No	`1024`	Altezza di output in pixel per modelli pixel-based come `venice-sd35`. Rifiutato dalla famiglia Qwen Image — vedi la nota qui sotto
`format`	string	No	`webp`	Formato di output: `jpeg`, `png` o `webp`
`variants`	integer	No	`1`	Numero di immagini da generare (`1`-`4`), solo quando `return_binary` è `false`. Un rifiuto esplicito da parte della content policy del provider può omettere singole varianti; vedi Risultati parziali delle varianti
`return_binary`	boolean	No	`false`	Restituisce i byte raw dell’immagine invece del JSON base64
`safe_mode`	boolean	No	`true`	Sfoca i contenuti per adulti quando abilitato
`seed`	integer	No	casuale	Riutilizza lo stesso seed per iterazioni più consistenti
`cfg_scale`	number	No	dipende dal modello	Valori più alti spingono il modello a seguire più da vicino il prompt
`lora_strength`	integer	No	-	Intensità (`0`-`100`) dei LoRA aggiuntivi usati da un modello. Vedi Intensità dei LoRA
`style_preset`	string	No	-	Applica uno stile preset da Image Styles
`style_references`	array	No	-	Immagini di riferimento di stile che guidano l’estetica dell’output. Ogni voce è `{ "image": <url or base64>, "strength": <0.1-1> }`. Solo modelli supportati; vedi Riferimenti di stile
`aspect_ratio`	string	Condizionale	-	Usato dai modelli che supportano il dimensionamento basato su ratio, come `qwen-image-2`, `gpt-image-2`, `nano-banana-2` e `nano-banana-pro`
`resolution`	string	Condizionale	-	Usato dai modelli che supportano tier di risoluzione come `1K`, `2K` o `4K`
`enable_web_search`	boolean	Condizionale	`false`	Permette ai modelli supportati di usare informazioni attuali dal web; aggiunge un costo extra
`transparent_background`	boolean	No	`false`	Restituisce un PNG o WebP con un vero canale alfa. Richiede un modello con `supportsTransparentBackground: true` e `format` `png` o `webp`. Consulta Immagini con sfondo trasparente

La validazione è specifica per ogni modello. Consulta Modelli di immagini e l’API Models prima di fare affidamento su un parametro tra più modelli.

Opzioni specifiche per modello

Generazione ad alta risoluzione

Alcuni modelli di immagini supportano aspect_ratio senza un tier di resolution selezionabile. Per esempio, qwen-image-2 accetta l’aspect ratio e lo mappa a dimensioni di output specifiche per il modello:

{
  "model": "qwen-image-2",
  "prompt": "Editorial product photo of a luxury watch on black marble, dramatic studio lighting",
  "aspect_ratio": "16:9"
}

Altri modelli di immagini supportano aspect_ratio più un tier di resolution. Per esempio, gpt-image-2, nano-banana-2 e nano-banana-pro supportano 1K, 2K e 4K:

{
  "model": "gpt-image-2",
  "prompt": "Editorial product photo of a luxury watch on black marble, dramatic studio lighting",
  "aspect_ratio": "16:9",
  "resolution": "4K"
}

{
  "model": "nano-banana-2",
  "prompt": "Editorial product photo of a luxury watch on black marble, dramatic studio lighting",
  "aspect_ratio": "16:9",
  "resolution": "2K"
}

Usa Modelli di immagini per vedere quali modelli supportano risoluzioni più alte e come sono prezzati.

Intensità dei LoRA

Alcuni modelli di immagini applicano LoRA aggiuntivi. lora_strength (integer, da 0 a 100) imposta quanto intensamente vengono applicati e ha effetto solo sui modelli che li usano. L’API non accetta file LoRA personalizzati e nessun endpoint elenca i LoRA usati da un modello. lora_strength è l’unico controllo sui LoRA.

Contenuti per adulti e safe mode

safe_mode controlla se i contenuti per adulti nell’output della generazione vengono sfocati. Il default è true, quindi le immagini classificate come per adulti vengono restituite sfocate a meno che tu non invii safe_mode: false:

{
  "model": "lustify-v8",
  "prompt": "…",
  "safe_mode": false
}

Le immagini per adulti (NSFW) non sfocate sono disponibili 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. Alcuni modelli di immagini sono progettati specificamente per la generazione per adulti / non censurata e si abbinano bene con safe_mode: false. Esempi presenti nella pagina dei prezzi includono lustify-sdxl, lustify-v7 e lustify-v8. Consulta Modelli di immagini e Prezzi per la lista attuale e i costi per modello. Per la modifica di immagini esistenti, il modello di editing di default è firered-image-edit. Le policy di contenuto variano in base al modello di edit; se hai bisogno di editing non censurato, usa qwen-edit-uncensored tramite Image Editing. Quando safe_mode è abilitato e il modello restituisce un output sfocato o moderato, ispeziona gli header di risposta x-venice-is-blurred e x-venice-is-content-violation se hai bisogno di rilevarlo a livello programmatico.

Usi un’app di terze parti? Le immagini per adulti restano sfocate a meno che l’app non invii safe_mode: false, oppure moderation: "low" sull’endpoint compatibile con OpenAI (vedi sotto).

Preset di stile

Se il modello selezionato lo supporta, style_preset ti permette di orientare l’output senza riscrivere l’intero prompt. Puoi recuperare i nomi dei preset validi da Image Styles:

{
  "model": "qwen-image-2",
  "prompt": "A futuristic Venice skyline at sunrise",
  "style_preset": "3D Model"
}

Consulta Image Styles per la lista degli stili attuale.

Riferimenti di stile

style_references va un passo oltre style_preset: invece di un preset con nome, condiziona la generazione su una o più immagini di riferimento. Ogni voce ha un image e uno strength opzionale:

{
  "model": "krea-v2-large",
  "prompt": "A quiet Venetian courtyard at golden hour",
  "style_references": [
    {
      "image": "https://example.com/reference-painting.png",
      "strength": 0.5
    }
  ]
}

Campo	Tipo	Obbligatorio	Descrizione
`image`	string	Sì	Immagine di riferimento come URL `http://` o `https://`, stringa base64 o data URI base64. Deve essere un’immagine raster (JPEG, PNG, WebP, HEIF, HEIC o AVIF), non può essere SVG e deve essere inferiore a 8 MB
`strength`	number	No	Quanto fortemente il riferimento guida l’output, da `0.1` a `1`. Il valore predefinito è `0.5`. Ignorato dai modelli in cui `supportsStyleReferenceStrength` è `false`

Il supporto varia in base al modello. Controlla GET /models?type=image:

model_spec.supportsStyleReferences è true solo sui modelli che accettano il campo.
model_spec.constraints.maxStyleReferences è il numero di voci che il modello accetta.
model_spec.constraints.supportsStyleReferenceStrength indica se strength ha effetto.

curl -s "https://api.venice.ai/api/v1/models?type=image" \
  | jq -r '.data[] | select(.model_spec.supportsStyleReferences == true) | "\(.id) max=\(.model_spec.constraints.maxStyleReferences)"'

Inviare style_references a un modello che non lo supporta restituisce 400, così come superare il limite del modello o inviare un riferimento corrotto, irraggiungibile o troppo grande. Alcuni modelli applicano una tariffa per il riferimento di stile per ogni immagine restituita, in aggiunta al prezzo base dell’immagine, ad esempio Krea v2 Large e Krea v2 Medium. La tariffa viene addebitata solo per le immagini effettivamente restituite. Consulta Image Models per i prezzi base per immagine.

Risultati parziali delle varianti

Con variants maggiore di 1, singole varianti possono essere rifiutate dalla content policy del provider mentre le altre vanno a buon fine. In tal caso l’endpoint restituisce comunque 200 con meno immagini di quelle richieste:

Quando una o più varianti vengono omesse, il body JSON include content_policy_violation_count, il numero di varianti omesse.
L’header di risposta x-venice-content-violation-count riporta lo stesso conteggio.
x-venice-is-content-violation e x-venice-is-blurred descrivono le immagini restituite.

Se tutte le varianti richieste vengono rifiutate, non viene restituita alcuna immagine e la richiesta fallisce invece con 422. Non dare per scontato che len(images) == variants; confronta la lunghezza dell’array con variants e, quando presente, controlla content_policy_violation_count.

Endpoint compatibile con OpenAI

Se stai già usando gli SDK di immagini OpenAI o integrazioni DALL-E esistenti, Venice supporta anche POST /images/generations. Offre un formato di richiesta più semplice, ma meno funzionalità rispetto all’endpoint nativo di Venice. Richiesta:

{
  "model": "z-image-turbo",
  "prompt": "A clean isometric illustration of an AI control room",
  "size": "1024x1024",
  "response_format": "b64_json"
}

size si applica solo ai modelli dimensionati in pixel, che hanno un widthHeightDivisor superiore a 1 in model_spec.constraints da GET /models?type=image. La maggior parte dei modelli, incluso qwen-image-2, dimensiona invece l’output in base ad aspect ratio e risoluzione e ignora size. Alcuni parametri OpenAI sono accettati per compatibilità con gli SDK ma vengono ignorati (n è limitato a 1):

Parametro	Comportamento su `/images/generations`
`quality`	Accettato e ignorato. La fatturazione usa il tier di qualità predefinito del modello
`style`	Accettato e ignorato
`output_compression`	Accettato e ignorato
`user`	Accettato, scartato e non è un alias di `anon_user_id`
`n`	È supportato solo `1`; altri valori vengono rifiutati dalla validazione

Su questo percorso non esiste il controllo del tier: non c’è un campo resolution o aspect_ratio, e quality non può aumentare o ridurre l’addebito. Per i modelli GPT Image a tier, usa l’endpoint nativo /image/generate quando devi scegliere quality, resolution o aspect_ratio. Usa il percorso compatibile con OpenAI per migrazioni più rapide. Usa /image/generate quando hai bisogno di opzioni specifiche di Venice come cfg_scale, style_preset, style_references, variants o risposte binarie.

Controllare la sfocatura dei contenuti per adulti su `/images/generations`

L’endpoint compatibile con OpenAI non accetta safe_mode. Inviarlo restituisce un 400 con Unrecognized key(s) in object: 'safe_mode'. Usa invece il parametro moderation in stile OpenAI:

Valore	Comportamento
`auto` (default)	Sfoca i contenuti per adulti, come `safe_mode: true`
`low`	Restituisce l’output senza sfocatura, come `safe_mode: false`

{
  "model": "lustify-v8",
  "prompt": "…",
  "size": "1024x1024",
  "response_format": "b64_json",
  "moderation": "low"
}

safe_mode funziona solo sull’endpoint nativo POST /image/generate. moderation funziona solo sull’endpoint compatibile con OpenAI POST /images/generations. La stessa distinzione vale per la trasparenza: /image/generate usa transparent_background: true, mentre /images/generations usa il parametro in stile OpenAI background: "transparent". Entrambi richiedono un formato di output png o webp e un modello con supportsTransparentBackground: true. Consulta Immagini con sfondo trasparente.

Consigli per il prompting

Inizia dal soggetto, poi aggiungi medium, illuminazione, composizione e atmosfera.
Metti i dettagli da evitare in negative_prompt invece di sovraccaricare il prompt principale.
Riutilizza il seed durante le iterazioni così puoi confrontare le modifiche al prompt senza cambiare completamente la composizione.
Mantieni il dimensionamento consapevole del modello. Alcuni modelli usano width/height, altri aspect_ratio e i modelli a tier di risoluzione usano aspect_ratio più resolution.
Usa variants durante l’esplorazione, poi torna a un singolo output una volta fissata la direzione.

Errori

Status	Significato	Azione
`400`	Parametri di richiesta non validi	Controlla nomi dei campi, tipi e vincoli specifici del modello
`401`	Autenticazione fallita o il modello richiede un tier di accesso superiore	Controlla la tua API key e l’accesso al modello
`402`	Saldo insufficiente	Aggiungi crediti su venice.ai/settings/api
`404`	Modello sconosciuto	Verifica l’ID del modello con `GET /models?type=image`
`415`	Content type non valido	Invia JSON con `Content-Type: application/json`
`422`	Violazione della content policy	Il provider ha rifiutato esplicitamente il prompt o l’immagine. Modifica il prompt o cambia modello. Il body include `error` e un booleano `retryable`, e può includere anche `suggested_prompt` e `recommended_model`
`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

Quando safe_mode è abilitato (o moderation è auto), ispeziona gli header di risposta come x-venice-is-blurred e x-venice-is-content-violation se devi rilevare gli esiti della moderazione in modo programmatico.

Modelli disponibili

Consulta Modelli di immagini per la lista attuale dei modelli, prezzi e funzionalità supportate.

Documentazione

Per iniziare

Testo e chat

Immagini

Video

Audio

Ricerca e RAG

Agenti e integrazioni

Strumenti di sviluppo

Strumenti per agenti

SDK e framework

Generazione di immagini

Endpoint

Passo 1: Invia una richiesta di generazione

Passo 2: Decodifica e salva l’immagine

Passo 3: Restituire binario invece di JSON (opzionale)

Passo 4: Elenca gli stili di immagine disponibili (opzionale)

Parametri della richiesta

Opzioni specifiche per modello

Generazione ad alta risoluzione

Intensità dei LoRA

Contenuti per adulti e safe mode

Preset di stile

Riferimenti di stile

Risultati parziali delle varianti

Endpoint compatibile con OpenAI

Controllare la sfocatura dei contenuti per adulti su `/images/generations`

Consigli per il prompting

Errori

Modelli disponibili

​Endpoint

​Passo 1: Invia una richiesta di generazione

​Passo 2: Decodifica e salva l’immagine

​Passo 3: Restituire binario invece di JSON (opzionale)

​Passo 4: Elenca gli stili di immagine disponibili (opzionale)

​Parametri della richiesta

​Opzioni specifiche per modello

​Generazione ad alta risoluzione

​Intensità dei LoRA

​Contenuti per adulti e safe mode

​Preset di stile

​Riferimenti di stile

​Risultati parziali delle varianti

​Endpoint compatibile con OpenAI

​Controllare la sfocatura dei contenuti per adulti su /images/generations

​Consigli per il prompting

​Errori

​Modelli disponibili

Endpoint

Passo 1: Invia una richiesta di generazione

Passo 2: Decodifica e salva l’immagine

Passo 3: Restituire binario invece di JSON (opzionale)

Passo 4: Elenca gli stili di immagine disponibili (opzionale)

Parametri della richiesta

Opzioni specifiche per modello

Generazione ad alta risoluzione

Intensità dei LoRA

Contenuti per adulti e safe mode

Preset di stile

Riferimenti di stile

Risultati parziali delle varianti

Endpoint compatibile con OpenAI

Controllare la sfocatura dei contenuti per adulti su `/images/generations`

Consigli per il prompting

Errori

Modelli disponibili