Génération d'images

La génération d’images sur Venice est synchrone. Envoyez un prompt à /image/generate et recevez votre image dans la même réponse, soit en base64 dans un JSON, soit sous forme binaire brute lorsque return_binary est true.

Endpoints

Endpoint	Objectif	Quand l’utiliser
`POST /image/generate`	API de génération d’images native de Venice	À utiliser pour bénéficier du support complet des fonctionnalités
`GET /image/styles`	Lister les presets de style disponibles	À utiliser avant d’envoyer `style_preset`
`POST /images/generations`	API de génération d’images compatible OpenAI	À utiliser lors de la migration de clients d’images OpenAI existants

Étape 1 : Envoyer une requête de génération

Le dimensionnement est spécifique au modèle. Certains modèles acceptent width et height explicites ; d’autres exposent aspect_ratio ; et les modèles à paliers de résolution exposent aspect_ratio plus des valeurs resolution telles que 1K, 2K ou 4K.

qwen-image, qwen-image-3, qwen-image-3-pro, qwen-image-2-1-turbo et qwen-image-2-1-pro n’acceptent plus width ni height. L’envoi de l’un ou l’autre renvoie 400 avec “width and height are no longer supported for this model. Use aspect_ratio instead.” Vérifiez model_spec.constraints depuis GET /models?type=image avant de choisir les champs de dimensionnement.

Exemple de dimensionnement basé sur les pixels :

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"
}

Exemple de dimensionnement par ratio d’aspect :

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"
}

Exemple de dimensionnement par palier de résolution :

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"
}

Le même schéma s’applique aux autres modèles à paliers de résolution :

{
  "model": "nano-banana-pro",
  "prompt": "A serene canal in Venice at sunset",
  "aspect_ratio": "16:9",
  "resolution": "2K"
}

Utilisez Modèles d’image ou l’API Models pour confirmer quels champs de dimensionnement chaque modèle accepte. Réponse (200) :

{
  "id": "generate-image-1234567890",
  "images": [
    "UklGRiIAAABXRUJQVlA4IBYAAAAwAQCdASoQABAAPm..."
  ],
  "timing": {
    "inferenceDuration": 1840,
    "inferencePreprocessingTime": 22,
    "inferenceQueueTime": 31,
    "total": 1893
  }
}

Le tableau images contient des données d’image encodées en base64. Décodez le premier élément pour l’enregistrer ou l’afficher. timing.total correspond à la durée complète de la requête en millisecondes.

Étape 2 : Décoder et enregistrer l’image

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']}")

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}`);

Étape 3 : Renvoyer du binaire au lieu de JSON (optionnel)

Si vous souhaitez que le corps de la réponse soit le fichier image lui-même, définissez return_binary: true. C’est utile lorsque vous voulez diffuser ou enregistrer l’image directement sans décodage 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
  }'

Lorsque return_binary est true, le corps de la réponse correspond à des données brutes image/jpeg, image/png ou image/webp selon le format que vous avez demandé.

variants n’est pris en charge que lorsque return_binary est false.

Étape 4 : Lister les styles d’image disponibles (optionnel)

Si vous souhaitez utiliser style_preset, récupérez d’abord les styles disponibles depuis /image/styles :

curl https://api.venice.ai/api/v1/image/styles

Cet endpoint est public et ne nécessite pas de clé API. Réponse (200) :

{
  "object": "list",
  "data": [
    "3D Model",
    "Analog Film",
    "Anime",
    "Cinematic",
    "Digital Art"
  ]
}

Les noms de styles se trouvent dans data, pas au niveau supérieur — lisez response.data plutôt que d’itérer directement sur l’objet de réponse. Puis transmettez l’une de ces valeurs dans votre requête de génération :

{
  "model": "qwen-image-2",
  "prompt": "A futuristic Venice skyline at sunrise",
  "style_preset": "Cinematic"
}

Utilisez l’endpoint des styles lorsque vous voulez les noms exacts des presets plutôt que de les deviner.

Paramètres de la requête

Paramètre	Type	Requis	Par défaut	Description
`model`	string	Oui	-	Identifiant du modèle à utiliser pour la génération
`prompt`	string	Oui	-	Ce qu’il faut générer
`negative_prompt`	string	Non	-	Ce qu’il faut éviter dans l’image
`width`	integer	Non	`1024`	Largeur de sortie en pixels pour les modèles basés sur les pixels tels que `venice-sd35`. Rejeté par la famille Qwen Image — voir la note ci-dessous
`height`	integer	Non	`1024`	Hauteur de sortie en pixels pour les modèles basés sur les pixels tels que `venice-sd35`. Rejeté par la famille Qwen Image — voir la note ci-dessous
`format`	string	Non	`webp`	Format de sortie : `jpeg`, `png` ou `webp`
`variants`	integer	Non	`1`	Nombre d’images à générer (`1`-`4`), uniquement lorsque `return_binary` est `false`. Un rejet explicite par la politique de contenu du fournisseur peut omettre certaines variantes ; voir Résultats partiels des variantes
`return_binary`	boolean	Non	`false`	Renvoyer les octets bruts de l’image au lieu de JSON base64
`safe_mode`	boolean	Non	`true`	Floute le contenu pour adultes lorsque activé
`seed`	integer	Non	aléatoire	Réutilisez la même seed pour des itérations plus cohérentes
`cfg_scale`	number	Non	dépend du modèle	Des valeurs plus élevées poussent le modèle à suivre le prompt plus étroitement
`style_preset`	string	Non	-	Applique un style préréglé depuis Image Styles
`style_references`	array	Non	-	Images de référence de style qui orientent l’esthétique de la sortie. Chaque entrée est `{ "image": <url or base64>, "strength": <0.1-1> }`. Modèles compatibles uniquement ; voir Références de style
`aspect_ratio`	string	Conditionnel	-	Utilisé par les modèles prenant en charge le dimensionnement basé sur le ratio, tels que `qwen-image-2`, `gpt-image-2`, `nano-banana-2` et `nano-banana-pro`
`resolution`	string	Conditionnel	-	Utilisé par les modèles prenant en charge les paliers de résolution tels que `1K`, `2K` ou `4K`
`enable_web_search`	boolean	Conditionnel	`false`	Permet aux modèles compatibles d’utiliser des informations web actuelles ; coût supplémentaire
`transparent_background`	boolean	Non	`false`	Renvoyer un PNG ou un WebP avec un véritable canal alpha. Nécessite un modèle avec `supportsTransparentBackground: true` et un `format` `png` ou `webp`. Voir Images à arrière-plan transparent

La validation est spécifique au modèle. Consultez Modèles d’image et l’API Models avant de compter sur un paramètre à travers plusieurs modèles.

Options spécifiques aux modèles

Génération haute résolution

Certains modèles d’image prennent en charge aspect_ratio sans palier resolution sélectionnable. Par exemple, qwen-image-2 accepte le ratio d’aspect et le mappe à des dimensions de sortie spécifiques au modèle :

{
  "model": "qwen-image-2",
  "prompt": "Editorial product photo of a luxury watch on black marble, dramatic studio lighting",
  "aspect_ratio": "16:9"
}

D’autres modèles d’image prennent en charge aspect_ratio plus un palier resolution. Par exemple, gpt-image-2, nano-banana-2 et nano-banana-pro prennent en charge 1K, 2K et 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"
}

Utilisez Modèles d’image pour voir quels modèles prennent en charge des résolutions plus élevées et comment ils sont tarifés.

Contenu adulte et mode sûr

safe_mode contrôle si le contenu adulte présent dans la sortie de génération est flouté. La valeur par défaut est true : les images classées comme adultes sont donc renvoyées floutées, sauf si vous envoyez safe_mode: false :

{
  "model": "lustify-v8",
  "prompt": "…",
  "safe_mode": false
}

Les images pour adultes (NSFW) non floutées sont disponibles pour tous les utilisateurs de l’API. Vous n’avez pas besoin d’un abonnement Pro, et le paramètre de filtre de contenu mature dans l’application Venice n’affecte pas les requêtes d’image effectuées via l’API. Certains modèles d’image sont spécifiquement conçus pour la génération adulte / non censurée et se combinent bien avec safe_mode: false. Parmi les exemples figurant sur la page de tarification, on trouve lustify-sdxl, lustify-v7 et lustify-v8. Voir Modèles d’image et Tarification pour la liste actuelle et les coûts par modèle. Pour l’édition d’images existantes, le modèle d’édition par défaut est firered-image-edit. Les politiques de contenu varient selon le modèle d’édition ; si vous avez besoin d’une édition non censurée, utilisez qwen-edit-uncensored via Édition d’image. Lorsque safe_mode est activé et que le modèle renvoie une sortie floutée ou modérée, inspectez les en-têtes de réponse x-venice-is-blurred et x-venice-is-content-violation si vous avez besoin de détecter cela de manière programmatique.

Vous utilisez une application tierce ? Les images pour adultes restent floutées sauf si l’application envoie safe_mode: false, ou moderation: "low" sur l’endpoint compatible OpenAI (voir ci-dessous).

Presets de style

Si le modèle sélectionné le prend en charge, style_preset vous permet d’orienter la sortie sans réécrire l’intégralité de votre prompt. Vous pouvez récupérer les noms valides des presets depuis Image Styles :

{
  "model": "qwen-image-2",
  "prompt": "A futuristic Venice skyline at sunrise",
  "style_preset": "3D Model"
}

Voir Image Styles pour la liste actuelle des styles.

Références de style

style_references va plus loin que style_preset : au lieu d’un preset nommé, il conditionne la génération à une ou plusieurs images de référence. Chaque entrée comporte un image et un strength optionnel :

{
  "model": "krea-v2-large",
  "prompt": "A quiet Venetian courtyard at golden hour",
  "style_references": [
    {
      "image": "https://example.com/reference-painting.png",
      "strength": 0.5
    }
  ]
}

Champ	Type	Requis	Description
`image`	string	Oui	Image de référence sous forme d’URL `http://` ou `https://`, de chaîne base64 ou de data URI base64. Doit être une image matricielle (JPEG, PNG, WebP, HEIF, HEIC ou AVIF), ne peut pas être un SVG et doit faire moins de 8 Mo
`strength`	number	Non	Intensité avec laquelle la référence oriente la sortie, de `0.1` à `1`. Vaut `0.5` par défaut. Ignoré par les modèles pour lesquels `supportsStyleReferenceStrength` est `false`

La prise en charge dépend du modèle. Consultez GET /models?type=image :

model_spec.supportsStyleReferences vaut true uniquement pour les modèles qui acceptent ce champ.
model_spec.constraints.maxStyleReferences indique le nombre d’entrées acceptées par le modèle.
model_spec.constraints.supportsStyleReferenceStrength indique si strength a un effet.

curl -s "https://api.venice.ai/api/v1/models?type=image" \
  | jq -r '.data[] | select(.model_spec.supportsStyleReferences == true) | "\(.id) max=\(.model_spec.constraints.maxStyleReferences)"'

Envoyer style_references à un modèle qui ne le prend pas en charge renvoie 400, tout comme le dépassement de la limite du modèle ou l’envoi d’une référence corrompue, inaccessible ou trop volumineuse. Certains modèles, par exemple Krea v2 Large et Krea v2 Medium, facturent des frais de référence de style pour chaque image renvoyée, en plus du prix de base de l’image. Ces frais ne sont facturés que pour les images effectivement renvoyées. Voir Modèles d’image pour les prix de base par image.

Résultats partiels des variantes

Avec variants supérieur à 1, certaines variantes peuvent être rejetées par la politique de contenu du fournisseur tandis que les autres réussissent. Dans ce cas, l’endpoint renvoie tout de même 200 avec moins d’images que demandé :

Lorsqu’une ou plusieurs variantes sont omises, le corps JSON inclut content_policy_violation_count, le nombre de variantes omises.
L’en-tête de réponse x-venice-content-violation-count contient le même nombre.
x-venice-is-content-violation et x-venice-is-blurred décrivent les images qui ont été renvoyées.

Si toutes les variantes demandées sont rejetées, aucune image n’est renvoyée et la requête échoue avec 422 à la place. Ne supposez pas que len(images) == variants ; comparez la longueur du tableau à variants et, le cas échéant, vérifiez content_policy_violation_count.

Endpoint compatible OpenAI

Si vous utilisez déjà les SDK d’image OpenAI ou des intégrations DALL-E existantes, Venice prend également en charge POST /images/generations. Il offre un format de requête plus simple, mais moins de fonctionnalités que l’endpoint natif de Venice. Requête :

{
  "model": "z-image-turbo",
  "prompt": "A clean isometric illustration of an AI control room",
  "size": "1024x1024",
  "response_format": "b64_json"
}

size ne s’applique qu’aux modèles dimensionnés en pixels, qui ont un widthHeightDivisor supérieur à 1 dans model_spec.constraints depuis GET /models?type=image. La plupart des modèles, dont qwen-image-2, dimensionnent plutôt la sortie selon le ratio d’aspect et la résolution, et ignorent size. Certains paramètres OpenAI sont acceptés pour la compatibilité avec les SDK mais sont ignorés (n est limité à 1) :

Paramètre	Comportement sur `/images/generations`
`quality`	Accepté et ignoré. La facturation utilise le palier de qualité par défaut du modèle
`style`	Accepté et ignoré
`output_compression`	Accepté et ignoré
`user`	Accepté, abandonné, et n’est pas un alias de `anon_user_id`
`n`	Seule la valeur `1` est prise en charge ; les autres valeurs sont rejetées par la validation

Le contrôle des paliers n’existe pas sur cette route : il n’y a pas de champ resolution ni aspect_ratio, et quality ne peut ni augmenter ni réduire le coût. Pour les modèles GPT Image à paliers, utilisez l’endpoint natif /image/generate lorsque vous devez choisir quality, resolution ou aspect_ratio. Utilisez la route compatible OpenAI pour des migrations plus rapides. Utilisez /image/generate lorsque vous avez besoin d’options spécifiques à Venice telles que cfg_scale, style_preset, style_references, variants ou des réponses binaires.

Contrôler le floutage du contenu adulte sur `/images/generations`

L’endpoint compatible OpenAI n’accepte pas safe_mode. Son envoi renvoie une erreur 400 avec Unrecognized key(s) in object: 'safe_mode'. Utilisez plutôt le paramètre moderation de style OpenAI :

Valeur	Comportement
`auto` (par défaut)	Floute le contenu adulte, comme `safe_mode: true`
`low`	Renvoie la sortie non floutée, comme `safe_mode: false`

{
  "model": "lustify-v8",
  "prompt": "…",
  "size": "1024x1024",
  "response_format": "b64_json",
  "moderation": "low"
}

safe_mode ne fonctionne que sur l’endpoint natif POST /image/generate. moderation ne fonctionne que sur l’endpoint compatible OpenAI POST /images/generations. La même séparation s’applique à la transparence : /image/generate utilise transparent_background: true, tandis que /images/generations utilise le paramètre de style OpenAI background: "transparent". Les deux nécessitent un format de sortie png ou webp et un modèle avec supportsTransparentBackground: true. Voir Images à arrière-plan transparent.

Conseils de prompting

Commencez par le sujet, puis ajoutez le médium, l’éclairage, la composition et l’ambiance.
Placez les détails à éviter absolument dans negative_prompt plutôt que de surcharger le prompt principal.
Réutilisez seed lors des itérations afin de comparer les changements de prompt sans modifier totalement la composition.
Adaptez le dimensionnement au modèle. Certains modèles utilisent width/height, d’autres aspect_ratio, et les modèles à paliers de résolution utilisent aspect_ratio plus resolution.
Utilisez variants pendant l’exploration, puis revenez à une seule sortie une fois la direction définie.

Erreurs

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 le modèle requiert un palier 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
`404`	Modèle inconnu	Vérifiez l’identifiant du modèle avec `GET /models?type=image`
`415`	Type de contenu invalide	Envoyez du JSON avec `Content-Type: application/json`
`422`	Violation de la politique de contenu	Le fournisseur a explicitement rejeté le prompt ou l’image. Ajustez le prompt ou changez de modèle. Le corps inclut `error` et un booléen `retryable`, et peut aussi inclure `suggested_prompt` et `recommended_model`
`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

Lorsque safe_mode est activé (ou que moderation vaut auto), inspectez les en-têtes de réponse tels que x-venice-is-blurred et x-venice-is-content-violation si vous devez détecter les résultats de modération de manière programmatique.

Modèles disponibles

Voir Modèles d’image pour la liste actuelle des modèles, les tarifs et le support des fonctionnalités.

Documentation

Démarrage

Texte et chat

Image

Vidéo

Audio

Recherche et RAG

Agents et intégrations

Outils de code

Outils pour agents

SDK et frameworks

Endpoints

Étape 1 : Envoyer une requête de génération

Étape 2 : Décoder et enregistrer l’image

Étape 3 : Renvoyer du binaire au lieu de JSON (optionnel)

Étape 4 : Lister les styles d’image disponibles (optionnel)

Paramètres de la requête

Options spécifiques aux modèles

Génération haute résolution

Contenu adulte et mode sûr

Presets de style

Références de style

Résultats partiels des variantes

Endpoint compatible OpenAI

Contrôler le floutage du contenu adulte sur `/images/generations`

Conseils de prompting

Erreurs

Modèles disponibles

​Endpoints

​Étape 1 : Envoyer une requête de génération

​Étape 2 : Décoder et enregistrer l’image

​Étape 3 : Renvoyer du binaire au lieu de JSON (optionnel)

​Étape 4 : Lister les styles d’image disponibles (optionnel)

​Paramètres de la requête

​Options spécifiques aux modèles

​Génération haute résolution

​Contenu adulte et mode sûr

​Presets de style

​Références de style

​Résultats partiels des variantes

​Endpoint compatible OpenAI

​Contrôler le floutage du contenu adulte sur /images/generations

​Conseils de prompting

​Erreurs

​Modèles disponibles

Endpoints

Étape 1 : Envoyer une requête de génération

Étape 2 : Décoder et enregistrer l’image

Étape 3 : Renvoyer du binaire au lieu de JSON (optionnel)

Étape 4 : Lister les styles d’image disponibles (optionnel)

Paramètres de la requête

Options spécifiques aux modèles

Génération haute résolution

Contenu adulte et mode sûr

Presets de style

Références de style

Résultats partiels des variantes

Endpoint compatible OpenAI

Contrôler le floutage du contenu adulte sur `/images/generations`

Conseils de prompting

Erreurs

Modèles disponibles