Prompt Enhancement

Il prompt enhancement riscrive il tuo prompt prima della generazione o della modifica dell’immagine per aggiungere dettagli visivi chiarificatori, trasformando descrizioni brevi o scarne in prompt più ricchi che i modelli di immagini seguono in modo più affidabile. Abilitalo impostando enhance_prompt: true su POST /image/generate, POST /image/edit o POST /image/multi-edit. Per la generazione di immagini, è lo stesso enhancement che alimenta la “bacchetta magica” nella web app di Venice. Per le modifiche di immagini, un enhancer vision-aware utilizza l’immagine o le immagini di input per chiarire la tua istruzione di edit.

Quando usarlo

Il prompt enhancement è più utile quando:

Il tuo prompt è breve (poche parole o una singola frase) e vuoi che il modello riempia composizione, illuminazione e atmosfera.
Stai sviluppando un prodotto in cui gli utenti finali digitano prompt informali che beneficiano dell’espansione.
Stai modificando un’immagine e vuoi che l’istruzione venga riscritta tenendo conto del suo contenuto visibile.
Vuoi un output più coerente e dettagliato senza scrivere a mano prompt lunghi.

Se invii già prompt lunghi e accuratamente elaborati, di solito otterrai un controllo migliore lasciando l’enhancement disattivato.

Passo 1: Invia una richiesta con l’enhancement abilitato

Aggiungi enhance_prompt: true a qualsiasi richiesta standard di generazione di immagini.

curl https://api.venice.ai/api/v1/image/generate \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "venice-sd35",
    "prompt": "a cabin in the woods",
    "enhance_prompt": true,
    "format": "webp"
  }'

Venice riscrive "a cabin in the woods" in un prompt più dettagliato, quindi usa il testo riscritto per la generazione. Il resto della richiesta si comporta esattamente come una normale chiamata di generazione.

L’enhancement aggiunge fino a ~30 secondi prima che la generazione inizi, perché la riscrittura è prodotta da una chiamata a un modello separato. Tienine conto nei timeout del client.

Passo 2: Leggi il prompt migliorato dall’header della risposta

Quando viene applicata una riscrittura, Venice restituisce il prompt finale codificato in URL nell’header di risposta x-venice-enhanced-prompt. Decodificalo per vedere, registrare o mostrare ciò che è stato effettivamente inviato al modello di immagine.

import base64
import os
from urllib.parse import unquote

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 cabin in the woods",
        "enhance_prompt": True,
        "format": "webp",
    },
)

data = response.json()

enhanced = response.headers.get("x-venice-enhanced-prompt")
if enhanced:
    print("Enhanced prompt:", unquote(enhanced))
else:
    print("No enhancement was applied; original prompt was used.")

image_bytes = base64.b64decode(data["images"][0])
with open("output.webp", "wb") as f:
    f.write(image_bytes)

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 cabin in the woods",
    enhance_prompt: true,
    format: "webp",
  }),
});

const data = await response.json();

const enhanced = response.headers.get("x-venice-enhanced-prompt");
if (enhanced) {
  console.log("Enhanced prompt:", decodeURIComponent(enhanced));
} else {
  console.log("No enhancement was applied; original prompt was used.");
}

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

L’header x-venice-enhanced-prompt è presente solo quando una riscrittura è stata effettivamente generata e applicata. Se l’enhancement viene saltato o fallisce, l’header è assente e viene usato il tuo prompt originale.

Uso dell’enhancement per le modifiche di immagini

Gli endpoint di edit usano un enhancer vision-aware che analizza l’immagine o le immagini di input prima di riscrivere l’istruzione. Questo aiuta a trasformare una richiesta breve come "make it winter" in una modifica più specifica, preservando i soggetti e la composizione rilevanti. Per un edit su singola immagine, includi enhance_prompt in una richiesta JSON o multipart:

curl https://api.venice.ai/api/v1/image/edit \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -o edited.png \
  -d '{
    "image": "https://example.com/cabin.jpg",
    "prompt": "make it winter",
    "enhance_prompt": true
  }'

Per multi-edit, usa lo stesso parametro con l’array images:

curl https://api.venice.ai/api/v1/image/multi-edit \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -o edited.png \
  -d '{
    "images": [
      "https://example.com/cabin.jpg",
      "https://example.com/snow-reference.jpg"
    ],
    "prompt": "make the first image match this winter atmosphere",
    "enhance_prompt": true
  }'

Entrambi gli endpoint di edit restituiscono l’immagine modificata come dati binari. Come per la generazione, ispeziona e decodifica in URL x-venice-enhanced-prompt per vedere la riscrittura applicata.

Comportamento

Aspetto	Comportamento
Endpoint supportati	`POST /image/generate`, `POST /image/edit` e `POST /image/multi-edit`
Default	`enhance_prompt` ha come default `false`; l’enhancement non avviene mai a meno che tu non lo richieda.
Fail-open	Se la riscrittura fallisce per qualsiasi motivo, la generazione o la modifica continua con il tuo prompt originale. La richiesta non genera un errore a causa dell’enhancement.
Edit consapevoli dell’immagine	Nelle richieste di edit, l’enhancer analizza l’immagine o le immagini fornite quando riscrive l’istruzione.
Limite di caratteri	Per la generazione, il prompt migliorato viene troncato al `promptCharacterLimit` del modello selezionato (vedi la Models API).
Safe mode	Nelle richieste di generazione, `safe_mode` viene rispettato durante l’enhancement. Con `safe_mode: true`, la riscrittura rimane SFW.
Header di risposta	Quando applicato, il prompt finale viene restituito codificato in URL in `x-venice-enhanced-prompt`.

Prezzi

Il prompt enhancement viene addebitato come un sovrapprezzo forfettario di $0,04 per riscrittura applicata, oltre al costo normale di generazione dell’immagine. Regole di fatturazione:

Vieni addebitato solo quando una riscrittura viene effettivamente generata e applicata. Se l’enhancement viene saltato o fa fail-open sul tuo prompt originale, non c’è alcun sovrapprezzo.
Il sovrapprezzo viene fatturato sul percorso di successo dell’immagine. Se la generazione termina con una violazione dei contenuti, l’enhancement non viene addebitato.
Quando richiedi più immagini con variants, la riscrittura condivisa viene fatturata al massimo una volta per richiesta, non una volta per variante.

Vedi Prezzi per i costi base della generazione di immagini.

Uso dell’enhancement con le variants

L’enhancement si abbina bene a variants quando esplori un’idea: viene generata una sola riscrittura, poi riutilizzata su ogni variante, quindi paghi il sovrapprezzo di $0,04 una sola volta.

curl https://api.venice.ai/api/v1/image/generate \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "venice-sd35",
    "prompt": "a cabin in the woods",
    "enhance_prompt": true,
    "variants": 4
  }'

variants è supportato solo quando return_binary è false. Vedi Generazione di immagini per i dettagli.

Consigli per il prompting

Mantieni il tuo prompt di input focalizzato sul soggetto e su eventuali dettagli non negoziabili. L’enhancement riempie stile, illuminazione e composizione intorno ad esso.
Registra l’header x-venice-enhanced-prompt durante lo sviluppo, così puoi capire cosa aggiunge l’enhancement e decidere quando preferisci scrivere i prompt a mano.
Per risultati di generazione ripetibili in un batch, genera una volta con l’enhancement, cattura il prompt migliorato dall’header, quindi riutilizza quello stesso testo con enhance_prompt disattivato.
Per la generazione di immagini, combina il prompt catturato con un seed fisso per confrontare altre modifiche di parametri senza dover riscrivere di nuovo.

Errori

L’enhancement in sé fa fail-open e non espone codici di errore propri. Gli errori standard della generazione di immagini si applicano comunque.

Status	Significato	Azione
`400`	Parametri di richiesta non validi	Controlla i nomi dei campi, i tipi e i 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
`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

Vedi il riferimento completo Codici di errore per i dettagli.

Correlati

Generazione di immagini — la guida completa alla generazione, inclusi dimensionamento, stili e risposte binarie.
Image Editing — edit su singola immagine, richieste multi-edit a strati e risposte binarie.
Generate Images (API reference) — ogni campo di richiesta e risposta per POST /image/generate.
Edit Image (API reference) — campi di richiesta per POST /image/edit.
Multi-Edit Image (API reference) — campi di richiesta per POST /image/multi-edit.
Modelli di immagini — elenco dei modelli, prezzi e promptCharacterLimit per modello.

Documentazione

Per iniziare

Testo e chat

Immagini, video e audio

Agenti e integrazioni

Strumenti di sviluppo

Strumenti per agenti

SDK e framework

Quando usarlo

Passo 1: Invia una richiesta con l’enhancement abilitato

Passo 2: Leggi il prompt migliorato dall’header della risposta

Uso dell’enhancement per le modifiche di immagini

Comportamento

Prezzi

Uso dell’enhancement con le variants

Consigli per il prompting

Errori

Correlati

​Quando usarlo

​Passo 1: Invia una richiesta con l’enhancement abilitato

​Passo 2: Leggi il prompt migliorato dall’header della risposta

​Uso dell’enhancement per le modifiche di immagini

​Comportamento

​Prezzi

​Uso dell’enhancement con le variants

​Consigli per il prompting

​Errori

​Correlati

Quando usarlo

Passo 1: Invia una richiesta con l’enhancement abilitato

Passo 2: Leggi il prompt migliorato dall’header della risposta

Uso dell’enhancement per le modifiche di immagini

Comportamento

Prezzi

Uso dell’enhancement con le variants

Consigli per il prompting

Errori

Correlati