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. 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 \
  -H "Authorization: Bearer $VENICE_API_KEY"

Risposta (200):

[
  "3D Model",
  "Analog Film",
  "Anime",
  "Cinematic",
  "Digital Art"
]

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` e `qwen-image`
`height`	integer	No	`1024`	Altezza di output in pixel per modelli pixel-based come `venice-sd35` e `qwen-image`
`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`
`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
`style_preset`	string	No	-	Applica uno stile preset da Image Styles
`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

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.

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.

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": "qwen-image-2",
  "prompt": "A clean isometric illustration of an AI control room",
  "size": "1024x1024",
  "response_format": "b64_json"
}

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, variants o risposte binarie.

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
`415`	Content type non valido	Invia JSON con `Content-Type: application/json`
`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 Venice è abilitato, 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.

Guides

Getting Started

Text & Chat

Image & Video

Agents & Integrations

Agent Tooling

Coding Tools

SDKs & Frameworks

Projects

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

Preset di stile

Endpoint compatibile con OpenAI

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

​Preset di stile

​Endpoint compatibile con OpenAI

​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

Preset di stile

Endpoint compatibile con OpenAI

Consigli per il prompting

Errori

Modelli disponibili