Générer des images à partir de consignes textuelles
🤖/image/generate génère des images à partir de consignes textuelles à l’aide de l’IA.

Exemple d’utilisation
Téléverser une source 1024×1024 dans le champ image et un masque de retouche blanc sur noir correspondant dans le champ mask. Cet exemple conserve chaque pixel décodé de la source en dehors du masque :
{
"steps": {
":original": {
"robot": "/upload/handle"
},
"inpainted": {
"format": "png",
"inpainting": "strict",
"model": "google/nano-banana-pro",
"prompt": "Replace the masked area with a breaching whale. Keep the rest of the image unchanged.",
"robot": "/image/generate",
"use": [
{
"as": "image",
"fields": "image",
"name": ":original"
},
{
"as": "mask",
"fields": "mask",
"name": ":original"
}
]
}
}
}Paramètres
interpolateboolean | Record<string, boolean>Détermine si les Assembly Variables sont interpolées pour chaque champ d’instruction.
Par défaut, la plupart des champs d’instruction des Robots interpolent les Assembly Variables. Définissez ce paramètre sur
falsepour traiter tous les champs d’instruction comme du texte littéral, ou définissez le chemin d’un champ individuel surfalsepour traiter uniquement ce champ comme du texte littéral. Pour les champs propres à un Robot qui sont littéraux par défaut, définissez ce paramètre surtrueou définissez le chemin de ce champ surtruepour réactiver l’interpolation.Utilisez des noms de champs tels que
path, ou des chemins avec points tels queffmpeg.vfpour les objets imbriqués.output_metaRecord<string, boolean> | boolean | Array<string>Demande des métadonnées coûteuses en CPU, désactivées par défaut pour accélérer les Assemblies.
Pour les images,
"has_transparency": truedétecte la transparence et"dominant_colors": trueextrait les couleurs hexadécimales. Ajoutez"dominant_colors_sampled": truepour obtenir plus rapidement des couleurs approximatives à partir de versions réduites de l’image. L’échantillonnage nécessitedominant_colorset ne modifie ni les octets de l’image ni la facturation. Sa méthode et sa palette peuvent varier. Omettez-le ou désactivez-le pour obtenir des couleurs en pleine résolution.Pour les images, vous pouvez également ajouter
"blurhash": truepour extraire une chaîne BlurHash — une représentation compacte d’un espace réservé pour l’image, utile pour afficher un aperçu flou pendant le chargement de l’image complète.Pour les images,
"thumbhash": trueextrait plutôt un ThumbHash encodé en base64 dansmeta.thumbhash, accompagné demeta.has_alpha(qui indique si un canal alpha existe, même lorsque l’image est entièrement opaque). Il décrit les pixels orientés selon les données EXIF et utilise la première image des images animées. L’extraction est effectuée au mieux : les images de plus de 40 mégapixels, les formats non pris en charge ou un échec de décodage ou un décodage limité ne produisent aucun espace réservé. Une extraction réussie ajoute des frais de métadonnées équivalents à 20 % des octets de ce fichier. Aucun supplément ThumbHash ne s’applique lorsque l’option est désactivée ou lorsqu’aucun hash n’est produit.Définissez cette option sur le Step qui produit l’image, par exemple
/upload/handlepour les originaux téléversés ou/image/resizepour les sorties traitées. La définir uniquement sur/transloadit/storene demande pas l’extraction : le stockage conserve les métadonnées du Step producteur. Transloadit Storage conserve un hash généré avec sa version immuable et le renvoie dans les résultats stockés et lors des lectures natives de ressources. Les téléversements directs vers S3 ne génèrent pas d’espaces réservés. Un espace réservé contient des informations sur l’image : protégez-le donc avec les mêmes contrôles d’accès que l’image complète.Pour les vidéos, vous pouvez ajouter le paramètre
"colorspace": truepour extraire l’espace colorimétrique de la vidéo de sortie.Pour les vidéos, vous pouvez également ajouter
"interlaced": truepour détecter si la vidéo est entrelacée. Cette option combine l’indicateur ffprobe peu coûteuxfield_orderavec une passe d’échantillonnageidetlimitée sur les premières images de la source, et exposeinterlaced,field_orderainsi qu’un objet de diagnosticinterlace_detectionsousfile.meta. Cette opération est coûteuse en calcul et facturée en conséquence.Pour l’audio, vous pouvez ajouter
"mean_volume": truepour obtenir une valeur unique représentant le volume moyen du fichier audio.Vous pouvez également définir cette option sur
falsepour ignorer l’extraction des métadonnées et accélérer le transcodage.user_metaRecord<string, any>(par défaut :{})Ajoute des métadonnées JSON personnalisées à chaque fichier émis sans modifier son contenu. Les objets et tableaux imbriqués sont pris en charge.
L’héritage dépend du Robot. Les valeurs sont fusionnées avec la valeur
user_metaexistante du fichier de sortie ; le Step actuel remplace les clés de premier niveau correspondantes. Attribuez explicitement les clés requises lorsqu’un Robot crée de nouvelles sorties.Dans les Steps de traitement,
${file.*}désigne la première entrée et${result.*}le fichier émis. Les valeurs sont évaluées pour chaque sortie après l’exécution du Robot, avant l’extraction ultérieure des métadonnées et le stockage temporaire. Sur:original, les valeurs sont évaluées pour chaque téléversement avant l’extraction des métadonnées.Les Steps en aval lisent
${file.user_meta.key}. Consultez Métadonnées personnalisées pour un exemple complet et les règles d’héritage.resultboolean(par défaut :false)Indique si les résultats de ce Step doivent figurer dans l’Assembly Status JSON
queuebatchDéfinir la file d’attente sur « batch » abaisse manuellement la priorité des Jobs de ce Step afin d’éviter de consommer des emplacements prioritaires de Jobs pour des Jobs qui n’ont pas besoin d’un temps d’attente nul dans la file
force_acceptboolean(par défaut :false)Forcer un Robot à accepter un type de fichier qu’il aurait ignoré.
Par défaut, les Robots ignorent les fichiers qu’ils ne connaissent pas. Le Robot 🤖/video/encode, par exemple, ignorera volontiers les images en entrée.
Avec le paramètre
force_acceptdéfini surtrue, vous pouvez forcer les Robots à accepter tous les fichiers qui leur sont envoyés. Cela entraîne généralement des erreurs et ne doit être utilisé que pour le débogage ou pour traiter des cas limites.ignore_errorsboolean | Array<meta | execute>(par défaut :[])Ignore les erreurs pendant certaines phases du traitement.
Si vous définissez cette valeur sur
["meta"], le Robot ignorera les erreurs lors de l’extraction des métadonnées.Si vous définissez cette valeur sur
["execute"], le Robot ignorera les erreurs lors de la phase d’exécution principale.Définir cette valeur sur
trueéquivaut à["meta", "execute"]: les erreurs seront alors ignorées dans les deux phases.usestring | Array<string> | Array<object> | objectIndique quel(s) Step(s) utiliser comme entrée.
Pour la retouche par masque (inpainting), sélectionnez l’image source et le masque avec des champs de téléversement ou des rôles
use.as.Plusieurs sélecteurs de source échouent avec « Supply exactly one inpainting source image. » Des sélecteurs de modification concurrents, y compris les deux rôles de modification sur une même entrée, échouent avec « Supply exactly one inpainting mask or cutout. » Un champ de modification prévaut sur les rôles de modification hérités.
Formes d’entrée acceptées :
- Sélectionner des champs d’image et de masque/découpe. Les champs prévalent sur les rôles hérités.
- Sans champs, utiliser les rôles d’image et de masque/découpe. Les entrées use répétées combinent leurs rôles.
- Combiner un champ d’image et un rôle de modification, ou un rôle d’image et un champ de modification.
- Avec un sélecteur de modification mais sans sélecteur d’image, la première entrée qui n’est pas un masque sert de source.
- Une découpe transparente avec intention d’image est sa propre source, y compris à côté de références.
- Les paires image+masque héritées utilisent la première source étiquetée comme source et la seconde comme masque ; les références n’influencent pas la sélection. Les champs prévalent.
- Replicate accepte 3 téléversements image+masque ou plus, utilise les deux premiers sauf si des champs les sélectionnent, et ignore les références.
- Seul Replicate accepte des entrées non étiquetées avec la source en premier et le masque en second, en respectant un sélecteur d’image unique.
- Le mode strict accepte une seule image transparente, y compris un téléversement de masque seul, comme source et découpe ; best_effort refuse la forme masque seul.
- Les autres entrées restent des références. Une transparence non étiquetée n’active jamais la modification best_effort de Google/OpenAI. Marquez les masques/découpes avec un champ ou un rôle use.as.
Formats de masque (la source et le masque doivent avoir des dimensions identiques) :
- Les masques noir et blanc opaques modifient le blanc et protègent le noir (seuil de moyenne RVB : 128). Utilisez du noir et du blanc pour éviter des couleurs opaques ambiguës.
- Un masque avec transparence modifie les pixels dont l’alpha est inférieur à 128 et protège les autres.
- Les masques verts hérités modifient les pixels dont l’alpha est d’au moins 128 lorsque chacun de ces pixels est vert (vert d’au moins 128 et supérieur au rouge et au bleu). Les pixels transparents sont protégés.
- Une découpe modifie l’alpha inférieur à 128. Une source distincte fournit les pixels protégés ; sinon, seuls les pixels restants de la découpe peuvent être conservés. À côté de références, donnez à la découpe un champ ou un rôle d’image pour la sélectionner comme source.
La source et le masque doivent être des images matricielles aux dimensions d’affichage identiques, d’au plus 40 000 000 pixels chacune (16 777 216 en mode strict). Le mode strict refuse les SVG/SVGZ ; le décodage best_effort les dessine une seule fois. Le mode au mieux applique l’orientation EXIF et utilise la première image ; le mode strict exige une seule image et l’orientation appliquée.
Les masques sont convertis pour chaque fournisseur. Modèles de retouche par masque pris en charge :
google/nano-banana,google/nano-banana-2,google/nano-banana-pro,openai/gpt-image-2,openai/gpt-image-2.5-flare,openai/gpt-image-2.5-sunburst,openai/gpt-image-2.6-flare,openai/gpt-image-2.6-sunburst,stability-ai/stable-diffusion-inpainting. L’alias héritégpt-image-2utilise la même route OpenAI. FLUX, Recraft et l’ancien Stable Diffusion auto-hébergé n’ont pas de route de retouche par masque ici ; les requêtes de retouche par masque sont refusées plutôt que d’ignorer silencieusement un masque. La génération ordinaire sans masque conserve son comportement existant.Sans le mode strict, l’image complète du fournisseur est renvoyée ; les masques ne font que la guider. Le contenu extérieur, les couleurs, la taille ou la transparence peuvent changer, même avec une graine fixe. Sélectionnez le mode strict pour obtenir des pixels extérieurs exacts. Les images auxiliaires telles que les gain maps ne sont pas conservées dans la sortie PNG en mode strict.
Le mode strict utilise le canevas source sans le redimensionner. Google exige un canevas natif : à 1K, Nano Banana accepte 1024×1024, 864×1184, 1184×864, 768×1344 ou 1344×768 ; Nano Banana Pro et Nano Banana 2 acceptent 1024×1024, 896×1200, 1200×896, 768×1376 ou 1376×768, les tailles 2× et 4× étant également acceptées dans la limite de pixels. Les côtés du canevas OpenAI doivent être des multiples de 16, ne pas dépasser 3840 pixels, avoir un rapport d’aspect d’au plus 3:1 et totaliser de 655 360 à 8 294 400 pixels. La retouche par masque Replicate exige que chaque côté soit un multiple de 64, de 64 à 1024 pixels. Les canevas non pris en charge échouent avant la génération ; un résultat du fournisseur inattendu et différent échoue également. Si nécessaire, redimensionnez ensemble la source et le masque dans un Step antérieur.
modelstringLe modèle d’IA à utiliser. La valeur par défaut est
openai/gpt-image-2.5-flare. Les modèles pris en charge incluentflux-1.1-pro-ultra,flux-schnell,recraft-v3,google/nano-banana,google/nano-banana-2,google/nano-banana-pro,openai/gpt-image-2,openai/gpt-image-2.5-flare,openai/gpt-image-2.5-sunburst,openai/gpt-image-2.6-flare,openai/gpt-image-2.6-sunburstetstability-ai/stable-diffusion-inpainting. L’alias héritégpt-image-2est également accepté pour assurer la rétrocompatibilité.prompt— obligatoirestringConsigne décrivant l’image souhaitée. Pour la retouche par remplissage génératif, décrivez ce qui doit apparaître dans la zone masquée/transparente et précisez que le reste doit rester inchangé.
formatjpeg | jpg | png | webp | svgFormat de sortie. Les valeurs par défaut dépendent du modèle : png pour les modèles Google et OpenAI, svg pour recraft-v3, jpeg pour les autres. Google peut renvoyer des octets JPEG en mode best_effort même si png est demandé ; le mode strict encode le PNG localement.
inpaintingbest_effort | strict(par défaut :"best_effort")best_effort normalise les masques et renvoie le résultat complet du fournisseur. strict copie les pixels RGBA décodés de la source en dehors du masque seuillé de façon stricte, et les pixels RGBA du fournisseur à l’intérieur, en préservant l’alpha ; aucun adoucissement des bords ni appel d’IA supplémentaire. Le mode strict exige des canevas matriciels correspondants, le format png, une source et une sortie sRGB 8 bits à image unique sans profils intégrés, ainsi qu’une orientation déjà appliquée. Les masques peuvent être en niveaux de gris 8 bits sans profils. Chaque image est limitée à 16 777 216 pixels. Les forfaits avec filigrane sont refusés. La largeur et la hauteur doivent correspondre à la source ; les dimensions omises reprennent sa taille. Omettez aspect_ratio. Les limites de canevas natives du modèle s’appliquent. Les entrées ou résultats incompatibles échouent. Les métadonnées PNG et les octets du fichier peuvent changer ; un redimensionnement, un filigrane ou un encodage avec perte en aval peuvent modifier les pixels.
seedstring | numberValeur d’initialisation du générateur de nombres aléatoires. Pour les modèles Google, utilisez un entier de 0 à 2147483647. Chaque sortie incrémente la valeur d’initialisation de 1, la valeur d’initialisation de la dernière sortie doit donc également se situer dans cet intervalle. Une valeur d’initialisation ne garantit pas des images identiques.
aspect_ratiostringRapport d’aspect de sortie demandé. Pour les modèles Google, les paramètres width/height peuvent également être utilisés et l’orientation est déduite automatiquement lorsque aspect_ratio est omis.
heightstring | numberHauteur de sortie demandée en pixels (principalement utilisée par les modèles d’image Google et OpenAI).
widthstring | numberLargeur de sortie demandée en pixels (principalement utilisée par les modèles d’image Google et OpenAI).
stylestringStyle de l’image générée.
num_outputsstring | numberNombre de variantes de sortie à générer (de 1 à 10).