Génération d'images
Génération et édition d'images synchrones. Pas de sondage de tâches.
Quand l'utiliser
- Texte vers image, image vers image, inpainting masqué.
- Fond transparent, sortie WebP/JPEG, GIF animé GPT-Image.
- L'utilisateur nomme un modèle d'image ou demande une taille, qualité ou format spécifique.
Quand ne pas l'utiliser
- Vidéo, musique, parole ou le modèle de décision Jev. Utilisez les compétences dédiées.
- L'utilisateur veut d'abord comparer les prix : exécutez
models --category image.
Prérequis
Résolvez la clé API dans cet ordre (la première correspondance gagne) :
skills/image-generation/config.json→api_keyskills/ai-gateway/config.json→api_keyAIGW_IMAGE_API_KEYAIGW_API_KEYOPENAI_API_KEY
Stockez une information d'identification avec :
python3 core/gateway.py login --key sk-xxx --skill image
--base-url écrit l'adresse de la passerelle dans le fichier de configuration. Ordre de résolution : config de la compétence, config partagée, AIGW_IMAGE_BASE_URL, AIGW_BASE_URL, puis la valeur par défaut embarquée dans core/config.json.
Commandes
# Texte vers image
python3 core/gateway.py image generate --prompt "un panda roux sur un banc, lumière douce" \
--model <model> --size 1024x1024 --quality high --output-format png
# Plusieurs images
python3 core/gateway.py image generate --prompt "planche d'autocollants" --n 4
# PNG transparent (nécessite un niveau de modèle prenant en charge la sortie alpha)
python3 core/gateway.py image generate --prompt "autocollant renard cartoon, bords nets" \
--background transparent --output-format png
# GIF animé (nécessite un niveau de modèle compatible GIF)
python3 core/gateway.py image generate --prompt "un petit robot fait un signe, en boucle" \
--output-format gif --frame-count 9 --frame-duration-ms 200
# Édition / inpainting
python3 core/gateway.py image edit --prompt "rendre le ciel orange au coucher du soleil" \
--image input.png --mask mask.png
# Édition avec un cercle de balisage transparent (GPT-Image 2.5+)
python3 core/gateway.py image edit --prompt "remplacer l'objet entouré par une pomme rouge" \
--image input.png --markup markup.png
# Découvrir les modèles et alias
python3 core/gateway.py models --category image
python3 core/gateway.py resolve nano-banana
Paramètres
| Drapeau | Requis | Remarques |
|---|---|---|
--prompt | oui | Description textuelle. |
--model | non | Identifiant exact du modèle. Omettre lorsqu'un seul modèle d'image est disponible. |
--size | non | 1024x1024, 1536x1024, auto ou valeurs spécifiques au modèle. Utilisez une variante de modèle -1k pour le niveau de prix le plus bas. |
--n | non | Nombre d'images. Limite stricte de 128. |
--quality | non | auto / low / medium / high ; GPT-Image 2.5+ ajoute xhigh, max. |
--output-format | non | png / jpeg / webp ; GPT-Image 2.6 ajoute svg, gif. |
--background | non | transparent nécessite png ou webp. |
--moderation | non | auto / low. |
--complexity | non | Profondeur de planification GPT-Image 2.6 low / medium / high. Ne change pas la facturation. |
--output-compression | non | 0-100, JPEG/WebP uniquement. |
--frame-count | non | 2-64, GIF uniquement. Doit être un entier non négatif. |
--frame-duration-ms | non | 20-2000, GIF uniquement. |
--markup | non | Édition uniquement. Superposition PNG transparente entourant la zone d'édition ; GPT-Image 2.5+ uniquement. |
--group | non | Router vers un groupe de facturation spécifique. |
Points d'accès
POST /v1/images/generations— JSON, synchrone.POST /v1/images/edits— multipart, nom de champimage[],maskoptionnel.
La réponse contient des éléments data[]. Chaque élément contient soit b64_json, soit url. Le CLI décode la base64, télécharge les URL et écrit les fichiers dans outputs/image/<YYYY-MM-DD>/. Si un téléchargement est refusé, l'URL d'origine est renvoyée dans urls.
Les modèles d'image Gemini acceptent aussi /v1/images/generations, avec size mappé à imageSize plus aspectRatio. Vérifié : 2048x2048 renvoie 2048x2048. GPT-Image 2.6 accepte également des tailles de pixels explicites ; vérifié 3840x2160 renvoie 3840x2160.
Résolution
| Besoin | Valeur de taille | Résultat |
|---|---|---|
| Carré 1K | 1024x1024 | 1024x1024 ou 1254x1254 |
| Carré 2K (Gemini) | 2048x2048 | 2048x2048 |
| Paysage 4K | 3840x2160 | 3840x2160 |
Utilisez une variante de modèle -1k pour le niveau de prix le plus bas ; les tailles plus grandes sont facturées au même prix par appel uniquement lorsque le modèle est à prix fixe.
Un identifiant de modèle se terminant par -1k (gpt-image-2.6-1k, -flare-1k, -sunburst-1k) renvoie toujours 1K. Demander 4K à celui-ci renvoie la taille demandée mais retourne silencieusement environ 1254x1254, alors vérifiez les dimensions de sortie au lieu de vous fier à la demande.
--output-format svg prend en charge --n 1 uniquement ; le fournisseur en amont rejette un lot plus grand. Limitez les demandes GIF/SVG à n=1 et fractionnez les lots vous-même.
Formats et transparence
| Capacité | Exigence |
|---|---|
png / jpeg / webp | Généralement disponibles. |
| Fond transparent | Nécessite png ou webp. Seuls les niveaux de modèle plus récents émettent de l'alpha ; les niveaux d'entrée le rejettent. |
| GIF animé | Modèles d'image générée à partir du niveau 2.6. Nécessite --output-format gif plus --frame-count (2-64) et --frame-duration-ms (20-2000). |
| Sortie SVG | Niveau 2.6 et supérieur, génération uniquement. Le point d'accès d'édition rejette svg et gif. |
Lorsqu'un format est rejeté avec un 400, le niveau de modèle sélectionné ne le prend pas en charge. Passez à un niveau plus récent plutôt que de réessayer le même modèle.
Certains modèles acceptent background: transparent sans erreur et renvoient néanmoins une image opaque. Vérifiez toujours le résultat au lieu de vous fier à la demande :
file outputs/image/<date>/<name>.png # "RGBA" ou "color_type 6" signifie un vrai alpha
Un résultat RGB signifie que le drapeau a été ignoré. Réessayez sur un niveau de modèle différent, ou post-traitez le fond blanc localement.
Édition
image edit télécharge les fichiers locaux en tant que multipart, donc l'image d'entrée n'a pas besoin d'être publique.
--imageest répétable ; jusqu'à 16 entrées sont acceptées.--maskmarque la zone de repeinture ;--markupentoure la région d'édition sur GPT-Image 2.5 et ultérieur, et est passé en tant que fichier multipart.- Le point d'accès d'édition accepte uniquement la sortie
png/jpeg/webp.svgetgifsont réservés à la génération. - L'image renvoyée conserve le cadrage d'entrée sauf si le prompt demande autre chose.
Vérifié : une image locale via image edit fonctionne à la fois sur un modèle GPT-Image et un modèle d'image Gemini, chacun renvoyant une image éditée avec la composition originale préservée.
Erreurs
| Statut | Signification | Action |
|---|---|---|
| 400 | Paramètre invalide ou capacité de modèle non prise en charge | Corrigez le drapeau ; vérifiez models --category image. |
| 401 | Clé manquante ou invalide | Relancez login, puis doctor. |
| 402 | Quota insuffisant | Dites à l'utilisateur de recharger. |
| 429 | Limite de taux ou plafond de concurrence | Reculez et réessayez. |
| 503 | Modèle non disponible dans le groupe de cette clé | Changez de modèle ou utilisez une clé de ce groupe. |
| 5xx | Défaillance en amont | Réessayez une fois, puis remontez le message textuellement. |