image_generate crée et modifie des images par l’intermédiaire des
fournisseurs configurés. Dans les sessions de conversation, il s’exécute de
manière asynchrone : OpenClaw enregistre une tâche en arrière-plan, renvoie
immédiatement l’identifiant de la tâche et réveille l’agent lorsque le
fournisseur a terminé. L’agent d’achèvement suit le mode normal de réponse
visible de la session : envoi automatique de la réponse finale lorsqu’il est
configuré, ou message(action="send") lorsque la session exige l’outil de
messagerie. Si la session du demandeur est inactive ou si son réveil actif
échoue, OpenClaw envoie directement une solution de repli idempotente avec les
images générées afin que le résultat ne soit pas perdu.
L’outil apparaît uniquement lorsqu’au moins un fournisseur de génération
d’images est disponible. Si
image_generate ne figure pas parmi les outils de
votre agent, configurez agents.defaults.imageGenerationModel, définissez une
clé d’API de fournisseur ou connectez-vous avec OAuth OpenAI ChatGPT/Codex.Démarrage rapide
1
Configurer l’authentification
Définissez une clé d’API pour au moins un fournisseur (par exemple
OPENAI_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY) ou connectez-vous
avec OAuth OpenAI Codex.2
Choisir un modèle par défaut (facultatif)
openai/gpt-image-2. Lorsqu’un profil OAuth openai est configuré,
OpenClaw achemine les requêtes d’images par ce profil OAuth au lieu
d’essayer d’abord OPENAI_API_KEY. Une configuration explicite de
models.providers.openai (clé d’API, URL de base personnalisée/Azure)
réactive l’acheminement direct par l’API OpenAI Images.3
Interroger l’agent
« Générez une image représentant une sympathique mascotte robot. »L’agent appelle automatiquement
image_generate. Aucune liste
d’autorisation d’outils n’est nécessaire : il est activé par défaut
lorsqu’un fournisseur est disponible. L’outil renvoie l’identifiant d’une
tâche en arrière-plan, puis l’agent d’achèvement envoie la pièce jointe
générée au moyen de l’outil message lorsqu’elle est prête.Acheminements courants
Le même outil gère la génération de texte en image et la modification à partir
d’images de référence. Utilisez
image pour une seule référence ou images
pour plusieurs. Pour les modèles Krea 2 sur fal, ces références sont envoyées
comme références de style plutôt que comme entrées à modifier. Les indications
de sortie prises en charge par le fournisseur, telles que quality,
outputFormat et background, sont transmises lorsqu’elles sont disponibles
et signalées comme ignorées lorsqu’un fournisseur ne déclare pas les prendre
en charge. La prise en charge intégrée des arrière-plans transparents est
propre à OpenAI ; les autres fournisseurs peuvent néanmoins préserver le canal
alpha PNG si leur moteur le produit.
Fournisseurs pris en charge
Utilisez
action: "list" pour examiner les fournisseurs et les modèles
disponibles lors de l’exécution :
action: "status" pour examiner la tâche active de génération
d’images de la session actuelle :
Capacités des fournisseurs
Paramètres de l’outil
string
requis
Invite de génération d’image. Requise pour
action: "generate"."generate" | "status" | "list"
défaut:"generate"
Utilisez
"status" pour examiner la tâche active de la session ou "list"
pour examiner les fournisseurs et les modèles disponibles lors de
l’exécution.string
Remplacement du fournisseur/modèle (par exemple
openai/gpt-image-2).
Utilisez openai/gpt-image-1.5 pour les arrière-plans OpenAI transparents.string
Chemin ou URL d’une seule image de référence pour le mode de modification.
string[]
Plusieurs images de référence pour le mode de modification ou les modèles
utilisant des références de style (jusqu’à 14 par l’intermédiaire de l’outil
partagé ; les limites propres au fournisseur continuent de s’appliquer).
string
Indication de taille :
1024x1024, 1536x1024, 1024x1536, 2048x2048,
3840x2160.string
Rapport d’aspect :
1:1, 2:1, 20:9, 19.5:9, 2:3, 3:2, 2.35:1,
3:4, 4:3, 4:5, 5:4, 9:16, 9:19.5, 9:20, 16:9, 21:9, 1:2,
4:1, 1:4, 8:1, 1:8. Les fournisseurs valident le sous-ensemble propre
à leur modèle."1K" | "2K" | "4K"
Indication de résolution.
"low" | "medium" | "high" | "auto"
Indication de qualité lorsque le fournisseur la prend en charge.
"png" | "jpeg" | "webp"
Indication du format de sortie lorsque le fournisseur le prend en charge.
"transparent" | "opaque" | "auto"
Indication d’arrière-plan lorsque le fournisseur la prend en charge. Utilisez
transparent avec outputFormat: "png" ou "webp" pour les fournisseurs
prenant en charge la transparence.number
Nombre d’images à générer (1 à 4).
number
Délai d’expiration facultatif de la requête au fournisseur, en millisecondes.
Lorsque Codex appelle
image_generate par l’intermédiaire d’outils
dynamiques, cette valeur propre à l’appel remplace toujours la valeur par
défaut configurée et est plafonnée à 600000 ms.string
Indication du nom du fichier de sortie.
object
Indications propres à OpenAI :
background, moderation,
outputCompression et user."raw" | "low" | "medium" | "high"
Contrôle de la créativité de fal Krea 2. La valeur par défaut est
medium.Tous les fournisseurs ne prennent pas en charge tous les paramètres. Lorsqu’un
fournisseur de repli prend en charge une option géométrique proche plutôt que
celle demandée exactement, OpenClaw choisit la taille, le rapport d’aspect ou
la résolution pris en charge les plus proches avant l’envoi. Les indications
de sortie non prises en charge sont supprimées pour les fournisseurs qui ne
déclarent pas les prendre en charge et sont signalées dans le résultat de
l’outil. Les résultats de l’outil indiquent les paramètres appliqués ;
details.normalization consigne toute conversion des valeurs demandées vers
les valeurs appliquées.Configuration
Sélection du modèle
Ordre de sélection des fournisseurs
OpenClaw essaie les fournisseurs dans l’ordre suivant :- Paramètre
modelde l’appel d’outil (si l’agent en spécifie un). imageGenerationModel.primarydans la configuration.imageGenerationModel.fallbacksdans l’ordre.- Détection automatique — uniquement les valeurs par défaut des fournisseurs disposant d’une authentification :
- le fournisseur par défaut actuel en premier ;
- les autres fournisseurs de génération d’images enregistrés, dans l’ordre de leur identifiant.
Les substitutions de modèle par appel sont exactes
Les substitutions de modèle par appel sont exactes
Une substitution de
model par appel essaie uniquement ce fournisseur et
ce modèle, sans poursuivre avec le modèle principal, les modèles de repli
configurés ni les fournisseurs détectés automatiquement.La détection automatique tient compte de l’authentification
La détection automatique tient compte de l’authentification
La valeur par défaut d’un fournisseur n’entre dans la liste des candidats
que lorsqu’OpenClaw peut réellement s’authentifier auprès de ce fournisseur.
Définissez
agents.defaults.mediaGenerationAutoProviderFallback: false
pour utiliser uniquement les entrées explicites model, primary et
fallbacks.Délais d’expiration
Délais d’expiration
Définissez
agents.defaults.imageGenerationModel.timeoutMs pour les
systèmes dorsaux de génération d’images lents. Un paramètre d’outil
timeoutMs fourni par appel remplace la valeur par défaut configurée, et
les valeurs par défaut configurées remplacent celles définies par le Plugin
du fournisseur. Les fournisseurs d’images hébergés par Google et OpenRouter
utilisent une valeur par défaut de 180 secondes ; la génération d’images
Microsoft Foundry MAI, xAI et Azure OpenAI utilise 600 secondes. Les appels
d’outils dynamiques de Codex utilisent une valeur par défaut de 120 secondes
pour le pont image_generate et respectent le même délai configuré, dans
la limite maximale de 600000 ms du pont d’outils dynamiques d’OpenClaw.Inspection à l’exécution
Inspection à l’exécution
Utilisez
action: "list" pour inspecter les fournisseurs actuellement
enregistrés, leurs modèles par défaut et les indications relatives aux
variables d’environnement d’authentification.Retouche d’images
OpenAI, OpenRouter, Google, DeepInfra, fal, Microsoft Foundry, MiniMax, ComfyUI et xAI prennent en charge la retouche d’images de référence. Les modèles Krea 2 sur fal utilisent les mêmes champsimage / images comme
références de style plutôt que comme entrées de retouche. Transmettez le
chemin ou l’URL d’une image de référence :
images ; xAI en prend en charge jusqu’à 3. fal prend en
charge 1 image de référence pour la conversion image vers image avec Flux,
jusqu’à 10 pour les retouches GPT Image 2, jusqu’à 10 références de style pour
Krea 2 et jusqu’à 14 pour les retouches Nano Banana 2. Microsoft Foundry,
MiniMax et ComfyUI en prennent en charge 1.
Présentation détaillée des fournisseurs
OpenAI gpt-image-2 (et gpt-image-1.5)
OpenAI gpt-image-2 (et gpt-image-1.5)
La génération d’images OpenAI utilise par défaut
openai/gpt-image-2. Si un profil OAuth openai est configuré,
OpenClaw réutilise le même profil OAuth que celui des modèles de
conversation de l’abonnement Codex et envoie la requête d’image par
l’intermédiaire du système dorsal Codex Responses. Les anciennes URL de
base Codex telles que https://chatgpt.com/backend-api sont normalisées
en https://chatgpt.com/backend-api/codex pour les requêtes d’images.
OpenClaw ne se rabat pas silencieusement sur OPENAI_API_KEY pour
cette requête. Pour imposer un acheminement direct par l’API OpenAI Images,
configurez explicitement models.providers.openai avec une clé d’API,
une URL de base personnalisée ou un point de terminaison Azure.Les modèles openai/gpt-image-1.5, openai/gpt-image-1 et
openai/gpt-image-1-mini peuvent toujours être sélectionnés explicitement.
Utilisez gpt-image-1.5 pour produire des fichiers PNG/WebP avec un
arrière-plan transparent ; l’API gpt-image-2 actuelle rejette
background: "transparent".gpt-image-2 prend en charge à la fois la génération texte vers image et
la retouche d’images de référence au moyen du même outil image_generate.
OpenClaw transmet prompt, count, size, quality, outputFormat
ainsi que les images de référence à OpenAI. OpenAI ne reçoit pas
directement aspectRatio ni resolution ; lorsque cela est possible,
OpenClaw les convertit en une valeur size prise en charge, sinon l’outil
les signale comme substitutions ignorées.Les options propres à OpenAI se trouvent sous l’objet openai :openai.background accepte transparent, opaque ou auto ; les
sorties transparentes nécessitent un outputFormat png ou webp ainsi
qu’un modèle d’image OpenAI prenant en charge la transparence. OpenClaw
achemine les requêtes avec arrière-plan transparent destinées par défaut à
gpt-image-2 vers gpt-image-1.5. openai.outputCompression s’applique
aux sorties JPEG/WebP et est ignoré pour les sorties PNG.L’indication de premier niveau background est indépendante du fournisseur
et correspond actuellement au même champ de requête OpenAI background
lorsque le fournisseur OpenAI est sélectionné. Les fournisseurs qui ne
déclarent pas prendre en charge les arrière-plans la renvoient dans
ignoredOverrides au lieu de recevoir ce paramètre non pris en charge.Pour acheminer la génération d’images OpenAI par l’intermédiaire d’un
déploiement Azure OpenAI plutôt que par api.openai.com, consultez
les points de terminaison Azure OpenAI.Modèles d’image Microsoft Foundry MAI
Modèles d’image Microsoft Foundry MAI
La génération d’images Microsoft Foundry utilise les noms des déploiements
d’image MAI déployés sous le préfixe de fournisseur Le fournisseur utilise l’API MAI de Microsoft Foundry, et non l’API
OpenAI Images :
microsoft-foundry/.
Il n’existe aucun modèle par défaut au niveau du fournisseur, car l’API MAI
attend le nom de votre déploiement dans le champ model :- Point de terminaison de génération :
/mai/v1/images/generations - Point de terminaison de retouche :
/mai/v1/images/edits - Authentification :
AZURE_OPENAI_API_KEY/ clé d’API du fournisseur, ou Entra ID viaaz login - Sortie : une image PNG
- Taille :
1024x1024par défaut ; la largeur et la hauteur doivent chacune être d’au moins 768 px, et le nombre total de pixels ne doit pas dépasser 1 048 576 - Retouches : une image de référence PNG ou JPEG, prise en charge uniquement par
les déploiements
MAI-Image-2.5-FlashetMAI-Image-2.5
MAI-Image-2.5-Flash ou
MAI-Image-2.5.Les modèles d’image MAI actuels sont MAI-Image-2.5-Flash,
MAI-Image-2.5, MAI-Image-2e et MAI-Image-2. Consultez le
Plugin Microsoft Foundry pour
connaître la configuration et le comportement des modèles de conversation.Modèles d’image OpenRouter
Modèles d’image OpenRouter
La génération d’images OpenRouter utilise la même clé
OpenClaw transmet
OPENROUTER_API_KEY et passe par l’API d’images des complétions de
conversation d’OpenRouter. Sélectionnez les modèles d’image OpenRouter
avec le préfixe openrouter/ :prompt, count, les images de référence et les
indications aspectRatio / resolution compatibles avec Gemini à
OpenRouter. Les raccourcis intégrés actuels vers les modèles d’image
OpenRouter comprennent google/gemini-3.1-flash-image-preview,
google/gemini-3-pro-image-preview et openai/gpt-5.4-image-2.
Utilisez action: "list" pour voir ce que votre Plugin configuré expose.fal Krea 2
fal Krea 2
Les modèles Krea 2 sur fal utilisent le schéma Krea natif de fal plutôt
que le schéma générique Krea 2 renvoie actuellement une image par requête. Privilégiez
image_size employé par Flux. OpenClaw envoie :aspect_ratiopour les indications de rapport d’aspectcreativity, avecmediumcomme valeur par défautimage_style_referenceslorsqueimageouimagesest fourni
aspectRatio pour Krea ; OpenClaw associe size au rapport d’aspect Krea
pris en charge le plus proche et rejette resolution pour Krea au lieu de
l’ignorer. Utilisez fal.creativity lorsque vous souhaitez définir un
niveau de créativité Krea natif :Double authentification MiniMax
Double authentification MiniMax
La génération d’images MiniMax est disponible par les deux modes
d’authentification MiniMax intégrés :
minimax/image-01pour les configurations avec clé d’APIminimax-portal/image-01pour les configurations OAuth
xAI grok-imagine-image
xAI grok-imagine-image
Le fournisseur xAI intégré utilise
/v1/images/generations pour les
requêtes contenant uniquement une invite et /v1/images/edits lorsque
image ou images est présent.- Modèles :
xai/grok-imagine-image,xai/grok-imagine-image-quality - Nombre : jusqu’à 4
- Références : un champ
imageou jusqu’à trois éléments dansimages - Rapports d’aspect :
1:1,16:9,9:16,4:3,3:4,3:2,2:3,2:1,1:2,19.5:9,9:19.5,20:9,9:20 - Résolutions :
1K,2K - Sorties : renvoyées sous forme de pièces jointes d’image gérées par OpenClaw
quality,
mask, user ni le rapport d’aspect auto tant que ces contrôles
n’existent pas dans le contrat image_generate partagé entre les
fournisseurs.Exemples
- Générer (paysage 4K)
- Générer (PNG transparent)
- Générer (faible qualité OpenAI)
- Générer (deux images carrées)
- Modifier (une référence)
- Modifier (plusieurs références)
- Références de style Krea
--output-format, --background, --quality et
--openai-moderation sont disponibles avec openclaw infer image edit ;
--openai-background reste un alias propre à OpenAI. À ce jour, les fournisseurs
intégrés autres qu’OpenAI ne déclarent pas de contrôle explicite de l’arrière-plan ;
background: "transparent" est donc signalé comme ignoré pour ces fournisseurs.
Voir aussi
- Vue d’ensemble des outils - tous les outils d’agent disponibles
- ComfyUI - configuration des workflows locaux ComfyUI et Comfy Cloud
- fal - configuration du fournisseur d’images et de vidéos fal
- Google (Gemini) - configuration du fournisseur d’images Gemini
- Plugin Microsoft Foundry - configuration du chat Microsoft Foundry et des images MAI
- MiniMax - configuration du fournisseur d’images MiniMax
- OpenAI - configuration du fournisseur OpenAI Images
- Vydra - configuration des images, des vidéos et de la synthèse vocale Vydra
- xAI - configuration des images, des vidéos, de la recherche, de l’exécution de code et de la synthèse vocale Grok
- Référence de configuration - configuration de
imageGenerationModel - Modèles - configuration des modèles et basculement en cas de défaillance