# Génération d'images

Permettez à l'agent de générer des images depuis un prompt texte via l'API Images d'OpenAI.

## Vue d'ensemble

`image_generation` expose une fonction qui prend un prompt et renvoie un ou plusieurs fichiers PNG / JPG / WebP. Chaque image est **persistée dans la table `generated_files` de votre compte** et servie via une URL signée — le LLM (et le panneau de chat de l'utilisateur) peut donc référencer l'image sans qu'on réuploade les octets partout.

À utiliser pour :

- Une illustration, esquisse de schéma ou image d'en-tête en ligne.
- Un workflow qui transforme une spec structurée en visuel (ex. *« email marketing avec image d'en-tête X »*).
- Un mock-up demandé par l'utilisateur.

À éviter pour : production de design fini (utilisez un outil dédié), édition d'image existante (non couvert ici — passez par un tool `function` qui appelle l'endpoint Edit d'OpenAI).

## Configuration

| Champ | Valeurs | Notes |
| --- | --- | --- |
| Modèle | `gpt-image-1`, `gpt-image-2`, `dall-e-3` | Les modèles récents acceptent `quality` et `background` ; `dall-e-3` non (on les retire automatiquement). |
| Taille | `1024x1024`, `1024x1792`, `1792x1024` | Carré, portrait, paysage. Les tailles invalides sont ramenées à `1024x1024`. |
| Qualité | `low`, `standard`, `high` | Plus c'est élevé, plus c'est net et coûteux. |
| Format | `png`, `jpg`, `webp` | Format de stockage. PNG préserve la transparence. |
| Arrière-plan | `auto`, `transparent`, `opaque` | Pris en compte uniquement par `gpt-image-*`. |

Le modèle peut aussi passer `size` et `quality` à chaque appel pour surcharger les valeurs par défaut.

## Exemple

Tour utilisateur : *« Génère une illustration flat d'un robot qui lit un livre, fond transparent. »*

Le LLM appelle :

```json
{
  "prompt": "Illustration flat d'un robot lisant un livre, pastel doux",
  "size": "1024x1024",
  "quality": "high"
}
```

Réponse backend renvoyée au modèle :

```json
{
  "status": "completed",
  "image_urls": ["https://app.systalink.fr/files/abc123/download?sig=..."],
  "images": [{
    "filename": "agent-image-abc12345.png",
    "url": "https://app.systalink.fr/files/abc123/download?sig=...",
    "preview_url": "https://app.systalink.fr/files/abc123/preview?sig=...",
    "public_id": "abc123...",
    "format": "png"
  }]
}
```

L'agent répond une phrase et l'image s'affiche dans le chat via l'URL de preview.

## Coût

Facturé par OpenAI à l'image, selon **modèle × taille × qualité** :

- `gpt-image-1` et `gpt-image-2` facturent au token (image d'entrée + sortie) ; `high` en 1792×1024 est la combinaison la plus chère.
- `dall-e-3` a un tarif fixe par image, `hd` (mappé depuis notre `high`) ≈ 2× `standard`.

Un seul appel `gpt-image-*` en haute qualité 1792×1024 peut coûter un ordre de grandeur de plus qu'une complétion chat — affichez-le à l'utilisateur si votre workflow génère automatiquement.

## Bonnes pratiques

- **Soyez précis.** *« Bannière hero, 16:9, style vectoriel, palette marine + sarcelle, sans texte »* donne un résultat plus prévisible que *« une belle bannière »*.
- **Fixez le modèle.** Si vous adoptez `gpt-image-2` standard, fixez-le dans la modale pour éviter un fallback silencieux.
- **Persistez `public_id`.** Les nœuds en aval peuvent référencer le fichier généré par son `public_id`, par exemple pour le joindre à un email.

## Pièges

- Sans OPENAI_API_KEY configuré côté backend, le tool renvoie `{"status": "error", "message": "OPENAI_API_KEY is not configured."}` et l'agent le remonte à l'utilisateur.
- `gpt-image-1` rejette `response_format` ; on le retire. `dall-e-3` rejette `background` ; idem. Consultez le log d'exécution si un appel revient vide.
- Maximum `n=4` images par appel. Au-delà, la valeur est plafonnée.

---

*Source: https://agentbuilder.systalink.sn/docs/tool-image-generation — human documentation.*
*Other language: [/docs-md/en/tool-image-generation.md](/docs-md/en/tool-image-generation.md).*
*Machine-readable index: [/llms.txt](/llms.txt).*