> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-mintlify-d2fddb8a.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Génération d'images
> Générez des images à partir de prompts textuels avec l'API d'image native de Venice ou l'endpoint d'images compatible OpenAI, avec contrôles de style et sortie binaire ou base64.
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`.
**Exemple de dimensionnement basé sur les pixels :**
```bash theme={null}
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 :**
```bash theme={null}
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 :**
```bash theme={null}
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 :
```json theme={null}
{
"model": "nano-banana-pro",
"prompt": "A serene canal in Venice at sunset",
"aspect_ratio": "16:9",
"resolution": "2K"
}
```
Utilisez [Modèles d'image](/models/image) ou l'[API Models](/api-reference/endpoint/models/list) pour confirmer quels champs de dimensionnement chaque modèle accepte.
**Réponse (200) :**
```json theme={null}
{
"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
```python Python theme={null}
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={null}
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.
```bash theme={null}
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` :
```bash theme={null}
curl https://api.venice.ai/api/v1/image/styles \
-H "Authorization: Bearer $VENICE_API_KEY"
```
**Réponse (200) :**
```json theme={null}
[
"3D Model",
"Analog Film",
"Anime",
"Cinematic",
"Digital Art"
]
```
Puis transmettez l'une de ces valeurs dans votre requête de génération :
```json theme={null}
{
"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` et `qwen-image` |
| `height` | integer | Non | `1024` | Hauteur de sortie en pixels pour les modèles basés sur les pixels tels que `venice-sd35` et `qwen-image` |
| `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` |
| `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](/api-reference/endpoint/image/styles) |
| `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 |
La validation est spécifique au modèle. Consultez [Modèles d'image](/models/image) et l'[API Models](/api-reference/endpoint/models/list) 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 :
```json theme={null}
{
"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` :
```json theme={null}
{
"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={null}
{
"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](/models/image) pour voir quels modèles prennent en charge des résolutions plus élevées et comment ils sont tarifés.
### 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](/api-reference/endpoint/image/styles) :
```json theme={null}
{
"model": "qwen-image-2",
"prompt": "A futuristic Venice skyline at sunrise",
"style_preset": "3D Model"
}
```
Voir [Image Styles](/api-reference/endpoint/image/styles) pour la liste actuelle des styles.
***
## 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 :**
```json theme={null}
{
"model": "qwen-image-2",
"prompt": "A clean isometric illustration of an AI control room",
"size": "1024x1024",
"response_format": "b64_json"
}
```
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`, `variants` ou des réponses binaires.
***
## Conseils de prompting
1. Commencez par le sujet, puis ajoutez le médium, l'éclairage, la composition et l'ambiance.
2. Placez les détails à éviter absolument dans `negative_prompt` plutôt que de surcharger le prompt principal.
3. Réutilisez `seed` lors des itérations afin de comparer les changements de prompt sans modifier totalement la composition.
4. 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`.
5. 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](https://venice.ai/settings/api) |
| `415` | Type de contenu invalide | Envoyez du JSON avec `Content-Type: application/json` |
| `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 Venice est activé, 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](/models/image) pour la liste actuelle des modèles, les tarifs et le support des fonctionnalités.