> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Generazione di immagini
> Genera immagini da prompt testuali con l'API immagini nativa di Venice o l'endpoint OpenAI-compatibile, con stili e output binario o base64.
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:**
```bash theme={"system"}
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:**
```bash theme={"system"}
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:**
```bash theme={"system"}
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:
```json theme={"system"}
{
"model": "nano-banana-pro",
"prompt": "A serene canal in Venice at sunset",
"aspect_ratio": "16:9",
"resolution": "2K"
}
```
Usa [Modelli di immagini](/models/image) o l'[API Models](/api-reference/endpoint/models/list) per confermare quali campi di dimensionamento accetta ciascun modello.
**Risposta (200):**
```json theme={"system"}
{
"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
```python Python theme={"system"}
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']}")
```
```javascript Node.js theme={"system"}
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.
```bash theme={"system"}
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`:
```bash theme={"system"}
curl https://api.venice.ai/api/v1/image/styles \
-H "Authorization: Bearer $VENICE_API_KEY"
```
**Risposta (200):**
```json theme={"system"}
[
"3D Model",
"Analog Film",
"Anime",
"Cinematic",
"Digital Art"
]
```
Poi passa uno di questi valori nella tua richiesta di generazione:
```json theme={"system"}
{
"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](/api-reference/endpoint/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](/models/image) e l'[API Models](/api-reference/endpoint/models/list) 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:
```json theme={"system"}
{
"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`:
```json theme={"system"}
{
"model": "gpt-image-2",
"prompt": "Editorial product photo of a luxury watch on black marble, dramatic studio lighting",
"aspect_ratio": "16:9",
"resolution": "4K"
}
```
```json theme={"system"}
{
"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](/models/image) 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](/api-reference/endpoint/image/styles):
```json theme={"system"}
{
"model": "qwen-image-2",
"prompt": "A futuristic Venice skyline at sunrise",
"style_preset": "3D Model"
}
```
Consulta [Image Styles](/api-reference/endpoint/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:**
```json theme={"system"}
{
"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
| 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](https://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](/models/image) per la lista attuale dei modelli, prezzi e funzionalità supportate.