> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/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 native de Venice ou l'endpoint compatible OpenAI, en 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={"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"
}
```
**Exemple de dimensionnement par ratio d'aspect :**
```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"
}
```
**Exemple de dimensionnement par palier de résolution :**
```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"
}
```
Le même schéma s'applique aux autres modèles à paliers de résolution :
```json theme={"system"}
{
"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={"system"}
{
"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={"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}`);
```
## É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={"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
}'
```
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={"system"}
curl https://api.venice.ai/api/v1/image/styles \
-H "Authorization: Bearer $VENICE_API_KEY"
```
**Réponse (200) :**
```json theme={"system"}
[
"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={"system"}
{
"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={"system"}
{
"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={"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"
}
```
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={"system"}
{
"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={"system"}
{
"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.