Amélioration de prompt | Documentation de l'API Venice

L’amélioration de prompt réécrit votre prompt avant la génération ou l’édition d’images afin d’ajouter des détails visuels clarifiants, transformant des descriptions courtes ou éparses en prompts plus riches que les modèles d’image suivent plus fidèlement. Activez-la en définissant enhance_prompt: true sur POST /image/generate, POST /image/edit ou POST /image/multi-edit. Pour la génération d’images, il s’agit de la même amélioration qui alimente la « baguette magique » dans l’application web Venice. Pour les éditions d’images, un enhancer conscient de l’image utilise l’image ou les images d’entrée pour clarifier votre instruction d’édition.

Quand l’utiliser

L’amélioration de prompt est particulièrement utile lorsque :

Votre prompt est court (quelques mots ou une seule phrase) et vous souhaitez que le modèle complète la composition, l’éclairage et l’ambiance.
Vous développez un produit dans lequel les utilisateurs finaux tapent des prompts informels qui bénéficient d’une expansion.
Vous éditez une image et souhaitez que l’instruction soit réécrite en tenant compte de son contenu visible.
Vous voulez une sortie plus cohérente et détaillée sans avoir à rédiger manuellement de longs prompts.

Si vous envoyez déjà des prompts longs et soigneusement rédigés, vous obtiendrez généralement un meilleur contrôle en laissant l’amélioration désactivée.

Étape 1 : Envoyer une requête avec l’amélioration activée

Ajoutez enhance_prompt: true à n’importe quelle requête standard de génération d’images.

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 réécrit "a cabin in the woods" en un prompt plus détaillé, puis utilise le texte réécrit pour la génération. Le reste de la requête se comporte exactement comme un appel de génération normal.

L’amélioration ajoute jusqu’à ~30 secondes avant le démarrage de la génération, car la réécriture est produite par un appel de modèle distinct. Prenez cela en compte dans les timeouts de votre client.

Étape 2 : Lire le prompt amélioré depuis l’en-tête de réponse

Lorsqu’une réécriture est appliquée, Venice renvoie le prompt final encodé en URL dans l’en-tête de réponse x-venice-enhanced-prompt. Décodez-le pour voir, journaliser ou afficher ce qui a réellement été envoyé au modèle d’image.

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’en-tête x-venice-enhanced-prompt n’est présent que lorsqu’une réécriture a effectivement été générée et appliquée. Si l’amélioration est ignorée ou échoue, l’en-tête est absent et votre prompt original est utilisé.

Utiliser l’amélioration pour les éditions d’images

Les endpoints d’édition utilisent un enhancer conscient de l’image qui analyse l’image ou les images d’entrée avant de réécrire l’instruction. Cela permet de transformer une requête courte telle que "make it winter" en une édition plus spécifique tout en préservant les sujets et la composition pertinents. Pour une édition d’une seule image, incluez enhance_prompt dans une requête JSON ou 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
  }'

Pour multi-edit, utilisez le même paramètre avec le tableau 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
  }'

Les deux endpoints d’édition renvoient l’image éditée sous forme de données binaires. Comme pour la génération, inspectez et décodez l’URL de x-venice-enhanced-prompt pour voir la réécriture appliquée.

Comportement

Aspect	Comportement
Endpoints pris en charge	`POST /image/generate`, `POST /image/edit` et `POST /image/multi-edit`
Valeur par défaut	`enhance_prompt` vaut `false` par défaut ; l’amélioration ne se produit jamais sans opt-in.
Fail-open	Si la réécriture échoue pour une raison quelconque, la génération ou l’édition se poursuit avec votre prompt original. La requête ne renvoie pas d’erreur à cause de l’amélioration.
Éditions conscientes de l’image	Sur les requêtes d’édition, l’enhancer analyse l’image ou les images fournies lors de la réécriture de l’instruction.
Limite de caractères	Pour la génération, le prompt amélioré est tronqué à la valeur `promptCharacterLimit` du modèle sélectionné (voir l’API Models).
Safe mode	Sur les requêtes de génération, `safe_mode` est respecté pendant l’amélioration. Avec `safe_mode: true`, la réécriture reste SFW.
En-tête de réponse	Lorsqu’elle est appliquée, le prompt final est renvoyé encodé en URL dans `x-venice-enhanced-prompt`.

Tarification

L’amélioration de prompt est facturée sous forme de supplément forfaitaire de 0,04 $ par réécriture appliquée, en plus du coût normal de génération d’images. Règles de facturation :

Vous n’êtes facturé que lorsqu’une réécriture est effectivement générée et appliquée. Si l’amélioration est ignorée ou échoue en revenant à votre prompt original, il n’y a pas de supplément.
Le supplément est facturé sur le chemin de succès de l’image. Si la génération se termine par une violation de contenu, l’amélioration n’est pas facturée.
Lorsque vous demandez plusieurs images avec variants, la réécriture partagée est facturée au plus une fois par requête, et non une fois par variante.

Consultez Tarification pour les coûts de base de la génération d’images.

Utiliser l’amélioration avec les variantes

L’amélioration se marie bien avec variants lors de l’exploration d’une idée : une réécriture est générée, puis réutilisée pour chaque variante, de sorte que vous ne payez le supplément de 0,04 $ qu’une seule fois.

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 n’est pris en charge que lorsque return_binary est false. Voir Génération d’images pour plus de détails.

Conseils de prompting

Concentrez votre prompt d’entrée sur le sujet et tout détail non négociable. L’amélioration ajoute autour le style, l’éclairage et la composition.
Journalisez l’en-tête x-venice-enhanced-prompt pendant le développement afin d’apprendre ce que l’amélioration ajoute et de décider quand vous préféreriez écrire les prompts à la main.
Pour des résultats de génération reproductibles sur un lot, générez une fois avec l’amélioration, capturez le prompt amélioré depuis l’en-tête, puis réutilisez ce texte exact avec enhance_prompt désactivé.
Pour la génération d’images, combinez le prompt capturé avec un seed fixe pour comparer d’autres changements de paramètres sans avoir à réécrire.

Erreurs

L’amélioration elle-même échoue en fail-open et ne remonte pas ses propres codes d’erreur. Les erreurs standard de génération d’images s’appliquent toujours.

Statut	Signification	Action
`400`	Paramètres de requête invalides	Vérifiez les noms de champs, les types et les contraintes spécifiques au modèle
`401`	Échec d’authentification ou modèle nécessitant un niveau d’accès supérieur	Vérifiez votre clé API et votre accès au modèle
`402`	Solde insuffisant	Ajoutez des crédits sur venice.ai/settings/api
`429`	Limite de débit dépassée ou modèle surchargé	Réessayez avec un backoff ; vérifiez l’en-tête `Retry-After`
`500`	Échec du traitement d’inférence	Réessayez la requête
`503`	Modèle à pleine capacité	Réessayez après un court délai

Consultez la référence complète des Codes d’erreur pour plus de détails.

Liens associés

Génération d’images — le guide complet de génération, y compris le dimensionnement, les styles et les réponses binaires.
Édition d’images — éditions d’une seule image, requêtes multi-edit en couches et réponses binaires.
Générer des images (référence API) — chaque champ de requête et de réponse pour POST /image/generate.
Éditer une image (référence API) — champs de requête pour POST /image/edit.
Multi-Edit d’image (référence API) — champs de requête pour POST /image/multi-edit.
Modèles d’image — liste des modèles, tarification et promptCharacterLimit par modèle.

​Quand l’utiliser

​Étape 1 : Envoyer une requête avec l’amélioration activée

​Étape 2 : Lire le prompt amélioré depuis l’en-tête de réponse

​Utiliser l’amélioration pour les éditions d’images

​Comportement

​Tarification

​Utiliser l’amélioration avec les variantes

​Conseils de prompting

​Erreurs

​Liens associés

Quand l’utiliser

Étape 1 : Envoyer une requête avec l’amélioration activée

Étape 2 : Lire le prompt amélioré depuis l’en-tête de réponse

Utiliser l’amélioration pour les éditions d’images

Comportement

Tarification

Utiliser l’amélioration avec les variantes

Conseils de prompting

Erreurs

Liens associés