Vai al contenuto principale
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

EndpointScopoQuando usarlo
POST /image/generateAPI di generazione di immagini nativa di VeniceUsalo per il supporto completo delle funzionalità
GET /image/stylesElenco dei preset di stile disponibiliUsalo prima di inviare style_preset
POST /images/generationsAPI di generazione di immagini compatibile con OpenAIUsalo 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']}")

​
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

ParametroTipoObbligatorioDefaultDescrizione
modelstringSì-ID del modello da usare per la generazione
promptstringSì-Cosa generare
negative_promptstringNo-Cosa evitare nell’immagine
widthintegerNo1024Larghezza di output in pixel per modelli pixel-based come venice-sd35 e qwen-image
heightintegerNo1024Altezza di output in pixel per modelli pixel-based come venice-sd35 e qwen-image
formatstringNowebpFormato di output: jpeg, png o webp
variantsintegerNo1Numero di immagini da generare (1-4), solo quando return_binary è false
return_binarybooleanNofalseRestituisce i byte raw dell’immagine invece del JSON base64
safe_modebooleanNotrueSfoca i contenuti per adulti quando abilitato
seedintegerNocasualeRiutilizza lo stesso seed per iterazioni più consistenti
cfg_scalenumberNodipende dal modelloValori più alti spingono il modello a seguire più da vicino il prompt
style_presetstringNo-Applica uno stile preset da Image Styles
aspect_ratiostringCondizionale-Usato dai modelli che supportano il dimensionamento basato su ratio, come qwen-image-2, gpt-image-2, nano-banana-2 e nano-banana-pro
resolutionstringCondizionale-Usato dai modelli che supportano tier di risoluzione come 1K, 2K o 4K
enable_web_searchbooleanCondizionalefalsePermette 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

  1. Inizia dal soggetto, poi aggiungi medium, illuminazione, composizione e atmosfera.
  2. Metti i dettagli da evitare in negative_prompt invece di sovraccaricare il prompt principale.
  3. Riutilizza il seed durante le iterazioni così puoi confrontare le modifiche al prompt senza cambiare completamente la composizione.
  4. 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.
  5. Usa variants durante l’esplorazione, poi torna a un singolo output una volta fissata la direzione.

​
Errori

StatusSignificatoAzione
400Parametri di richiesta non validiControlla nomi dei campi, tipi e vincoli specifici del modello
401Autenticazione fallita o il modello richiede un tier di accesso superioreControlla la tua API key e l’accesso al modello
402Saldo insufficienteAggiungi crediti su venice.ai/settings/api
415Content type non validoInvia JSON con Content-Type: application/json
429Rate limit superato o modello sovraccaricoRiprova con backoff; controlla l’header Retry-After
500Elaborazione dell’inferenza fallitaRiprova la richiesta
503Modello 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.