> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-mintlify-f533effe.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Generazione di immagini
> Genera immagini da prompt testuali con l'API di Venice, coprendo le opzioni di dimensionamento dei modelli, i preset di stile, la forza dei LoRA, il safe mode e l'output binario.
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 |
| `lora_strength` | integer | No | - | Forza (`0`-`100`) dei LoRA integrati nel modello; ignorato dai modelli senza LoRA aggiuntivi |
| `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.
### Supporto LoRA
Alcuni modelli di immagini includono LoRA aggiuntivi integrati. Il parametro `lora_strength` (intero, da `0` a `100`) controlla con quanta forza vengono applicati questi LoRA integrati. Influisce solo sui modelli che usano LoRA aggiuntivi. Gli altri modelli lo ignorano.
L'API non supporta il caricamento di file LoRA personalizzati. Non esiste inoltre un endpoint che elenchi i LoRA inclusi in un modello. L'uso dei LoRA si limita a regolare `lora_strength` sui modelli che li includono.
### Contenuti per adulti e safe mode
`safe_mode` controlla se i contenuti per adulti nell'output della generazione vengono sfocati. Il default è `true`. Impostalo a `false` se il tuo caso d'uso ammette contenuti per adulti e vuoi l'output grezzo:
```json theme={"system"}
{
"model": "lustify-v8",
"prompt": "…",
"safe_mode": false
}
```
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](/models/image) e [Prezzi](/overview/pricing) per la lista attuale e i costi per modello.
Per la modifica di immagini esistenti, il modello di editing di default `qwen-edit` blocca le immagini sessuali esplicite. Se hai bisogno di editing non censurato, usa `qwen-edit-uncensored` tramite [Image Editing](/guides/media/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.
### 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.
### 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) | Abilita la modalità Safe Venice e sfoca i contenuti per adulti |
| `low` | Disabilita la modalità Safe Venice; restituisce l'output senza sfocatura |
```json theme={"system"}
{
"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`.
***
## 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?utm_source=venice-api-documentation) |
| `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.