Blog

Guide d'utilisation

Guide d'intégration d'Ideogram V3 Character Edit : comment préparer l'image source, le masque et l'image de référence du personnage

Trois types d'entrées d'image, chacun à son rôle : soumettre une édition locale selon les champs du contrat et vérifier point par point la cohérence du personnage et les bordures

Nov 18, 2026
Image de couverture du blog : sur un fond vert forêt profond, deux ensembles de bandes larges et aplaties s'entrecroisent pour former un quadrillage technique tissé, avec des inserts verticaux couleur laiton, dans un style géométrique sobre.
Sur cette page

Ce que gère chacun des trois types d'entrées d'image

Avant d'intégrer ideogram-v3-character/edit, commencez par séparer les responsabilités des trois champs d'image : toutes les actions de préparation qui suivent s'en trouveront clarifiées.

  • Image source image_url : détermine « quelle scène modifier ». Elle fournit la composition d'origine, l'arrière-plan et la position du sujet ; c'est la base de toute l'opération d'édition.
  • Masque mask_url : détermine « où modifier ». Il délimite uniquement la zone à repeindre ; le contenu en dehors de cette zone doit être conservé.
  • Images de référence du personnage reference_image_urls : détermine « à quoi ressemble le personnage ». Elles fournissent les traits physiques du personnage afin d'aligner le résultat de la repeinture sur le personnage de référence.

Ne mélangez pas les frontières des trois : l'image source n'est pas une image de référence du personnage, et l'image de référence du personnage ne peut pas remplacer l'image source ; le masque est une contrainte spatiale, pas une description de contenu. Confier les traits du personnage à l'image de référence, écrire le contenu de la scène dans prompt et confier la zone de modification au masque constitue la répartition la moins source d'erreurs. Dès qu'on les confond (par exemple en n'envoyant que l'image du personnage sans activer de masque, ou en utilisant le masque pour « suggérer » l'apparence du personnage), on perd tout repère pour diagnostiquer les problèmes.

Au niveau du contrat, l'image source et le masque sont des champs de type chaîne URL, tandis que les images de référence du personnage forment un champ tableau ; cette différence de type indique aussi une différence d'usage : les deux premiers forment une paire spatiale un à un, le dernier est une source indépendante de description du personnage.

Les trois types d'entrée ne se superposent pas en parallèle : l'image source, le masque et l'image de référence du personnage prennent chacun en charge des régions différentes de l'image de sortie ; le schéma exprime cette répartition par trois lignes convergentes.

Points clés de préparation de l'image source et du masque

image_url et mask_url sont tous deux des champs obligatoires, de format URI, devant commencer par http:// ou https:// (pattern de contrat ^https?://), avec une longueur minimale de 1.

Le rapport largeur/hauteur doit être identique

La seule contrainte géométrique stricte imposée par le contrat aux deux est la suivante : le masque doit conserver le même rapport largeur/hauteur que l'image source. Ce n'est pas une recommandation mais un prérequis ; la méthode la plus sûre lors de la préparation des ressources consiste à générer d'abord localement le masque aux dimensions de l'image source, puis à les envoyer ensemble, sans compter sur le serveur pour effectuer l'alignement.

Sémantique du masque : délimiter uniquement la zone à repeindre

Le masque marque les emplacements « autorisés à la repeinture ». Par conséquent :

  • les parties à conserver ne doivent pas tomber dans la zone du masque ;
  • le sujet à modifier (par exemple changement de tenue ou de posture) doit être entièrement contenu dans le masque, pour éviter que ses bords ne soient coupés ;
  • le masque ne doit pas être trop fragmenté : des petits blocs épars rendent l'intention d'édition difficile à comprendre pour le modèle.

Disponibilité des URL

Les deux champs sont des URL distantes : avant l'envoi, assurez-vous que les liens sont accessibles anonymement, qu'ils ne sont pas invalidés par une redirection et qu'ils ne nécessitent pas d'authentification. Pour le masque, privilégiez une image avec canal alpha ou un contraste noir et blanc net, afin d'éviter toute ambiguïté de bordure due à un dégradé semi-transparent.

Spécifications et limites des images de référence du personnage

reference_image_urls est un champ tableau obligatoire, avec des contraintes explicites du contrat : minItems: 1, maxItems: 1, c'est-à-dire exactement une image. En envoyer deux ou zéro sera considéré comme une entrée invalide ; cela va à l'encontre de l'intuition fréquente des « références multi-images » et constitue un piège courant lors de l'intégration.

Format et taille

  • Formats pris en charge : JPEG, PNG, WebP ;
  • Taille maximale de 10 MB par image.

Conseils de sélection d'image

L'image de référence du personnage sert à fournir des traits stables, donc :

  1. choisissez une image nette, de face ou presque de face, sans occlusion du visage ;
  2. évitez le contre-jour fort, les filtres lourds et les photos de groupe (le modèle ne peut pas déterminer qui aligner) ;
  3. le corps entier et le buste ont chacun leurs avantages : utilisez au moins un buste pour les détails vestimentaires, et un corps entier pour l'allure générale ;
  4. n'utilisez pas une image déjà dotée d'un arrière-plan complexe pour « suggérer » une scène — la scène doit être décrite dans prompt.

Bien que le tableau ne contienne qu'un seul élément, il faut tout de même l'envoyer sous forme de tableau, par exemple en encapsulant une URL unique dans un élément, et non en plaçant directement une chaîne.

Comment combiner champs obligatoires et facultatifs

Les champs obligatoires sont au nombre de quatre : prompt, image_url, mask_url, reference_image_urls. Les réglages facultatifs incluent expand_prompt, style, seed, rendering_speed.

prompt décrit la nouvelle scène, pas une instruction d'édition

La définition du contrat pour prompt est essentielle : « décrire la scène dans laquelle se trouve le personnage de référence, c'est-à-dire le contenu de l'image à générer lors de cette édition », longueur de 1 à 5000 caractères. Autrement dit, n'écrivez pas d'instruction opérationnelle du type « remplace sa veste par un manteau rouge », mais une description d'image comme « elle se tient dans une rue après la pluie, portant un manteau rouge, les néons se reflétant sur le sol mouillé ». La portée de l'édition est gérée par le masque, et prompt gère le contenu de l'image lui-même.

expand_prompt activé par défaut

expand_prompt est un interrupteur booléen, par défaut true ; lorsqu'il est activé, MagicPrompt développe automatiquement le prompt. Cela signifie que la brève description que vous soumettez sera retravaillée par le modèle. En phase de diagnostic, il est conseillé de conserver la valeur par défaut, puis de décider de le désactiver une fois la différence entre description longue et résultat développé bien comprise.

style et seed

  • L'énumération style vaut AUTO, REALISTIC, FICTION, par défaut AUTO. Pour un personnage réaliste, utilisez REALISTIC ; pour une illustration stylisée, FICTION ; en cas de doute, restez sur AUTO.
  • seed est un entier, de 0 à 2147483647, servant à reproduire le résultat de génération d'un même prompt. Pour comparer « même entrée, paramètres différents », fixer le seed permet d'éliminer l'interférence de l'aléatoire.

Choix du niveau rendering_speed

rendering_speed est une énumération de chaînes, par défaut BALANCED, avec trois niveaux :

  • TURBO : génération la plus rapide, adaptée à la validation rapide en phase de brouillon de la zone du masque et de la correspondance du personnage ;
  • BALANCED : niveau par défaut, compromis entre vitesse et détails, point de départ de l'intégration quotidienne ;
  • QUALITY : détails les plus riches, adapté aux cycles de finalisation avant la génération finale.

La logique de choix consiste à changer de niveau selon les phases, plutôt qu'à en figer un une fois pour toutes : commencez par TURBO pour vérifier que la géométrie et l'orientation du personnage sont correctes, puis affinez les détails avec BALANCED ou QUALITY. Ainsi, lors des débogages répétés, le temps n'est pas perdu dans un rendu de haute qualité.

Il faut souligner que les trois niveaux diffèrent en termes de facturation (facturation selon le niveau de génération) ; pour les prix précis, référez-vous au panneau tarifaire du site, cet article ne développe pas les chiffres. Lors du diagnostic de problèmes d'entrée d'image, fixer d'abord le niveau par défaut permet d'éliminer une variable.

Les trois niveaux ressemblent à la variation de densité d'un même tissage : plus le tissage est haut, plus il est serré, plus les détails sont nombreux et plus le rendu est lent.

Liste de vérification avant soumission

Vérifier chaque point selon le contrat permet d'écarter la plupart des échecs avant la soumission :

  • prompt non vide et ne dépassant pas 5000 caractères, avec un contenu décrivant une scène et non une instruction d'édition ;
  • image_url est un lien accessible anonymement commençant par http:// ou https:// ;
  • mask_url est également accessible et possède le même rapport largeur/hauteur que l'image source ;
  • reference_image_urls est un tableau de longueur exactement 1 ;
  • l'image de référence est au format JPEG/PNG/WebP et sa taille ne dépasse pas 10 MB ;
  • l'orthographe des champs facultatifs et les valeurs d'énumération sont correctes (style, rendering_speed utilisent les valeurs en majuscules listées dans le contrat) ;
  • si seed est défini, vérifiez qu'il s'agit d'un entier entre 0 et 2147483647 ;
  • si expand_prompt est désactivé, vérifiez que prompt est déjà suffisamment complet.

Cette liste constitue aussi le premier réflexe pour le dépannage : si une condition n'est pas remplie, corrigez d'abord l'entrée plutôt que de modifier sans cesse la description.

Méthode de diagnostic des écarts de personnage et des problèmes de bordure

Lorsque le résultat généré n'est pas à la hauteur, commencez par classer le problème, puis ajustez de manière ciblée ; c'est plus efficace que de resoumettre l'image entière.

Type 1 : le personnage ne ressemble pas

Cela se manifeste par un écart des traits du visage, de la coiffure ou de la morphologie par rapport à l'image de référence. Pistes d'ajustement :

  • changer l'image de référence : une image frontale plus nette, un meilleur éclairage, un sujet unique ;
  • vérifier que l'image de référence n'est pas tronquée ou trop compressée ;
  • ajouter une description du personnage dans prompt (vêtements, posture, âge, allure) pour que le texte et l'image se corroborent ;
  • réduire la complexité de la scène pour éviter que les éléments d'arrière-plan ne captent les détails du personnage.

Type 2 : les bords sont flous

Cela se manifeste par une modification inattendue du contenu hors du masque, ou par des jointures ou dédoublements sur les bords du masque. Pistes d'ajustement :

  • vérifier d'abord que le rapport largeur/hauteur de l'image source et du masque est strictement identique ;
  • vérifier si le masque englobe aussi des parties à conserver ;
  • faire en sorte que le sujet tombe entièrement dans le masque pour éviter les bords coupés ;
  • utiliser un bord de masque plus net afin de réduire les transitions semi-transparentes.

Ne traitez pas les deux types de problèmes en même temps : pour un problème de personnage, modifiez l'image de référence et la description ; pour un problème de bordure, modifiez le masque et la géométrie. Ne changez qu'une variable à la fois pour pouvoir déterminer laquelle a eu un effet.

De l'exemple à l'intégration

Traduire les exigences du contrat ci-dessus en un processus revient à quatre étapes : préparer une image source et un masque de même rapport largeur/hauteur, choisir une image de référence du personnage conforme, décrire la nouvelle scène avec un prompt scénarisé, puis vérifier les champs selon la liste avant de soumettre.

Le point d'entrée de l'intégration se trouve sur la page du modèle ; les définitions de champs et les valeurs d'énumération font foi sur cette page, et vous pouvez les comparer point par point avec la liste de cet article : page du modèle Ideogram V3 Character Edit. C'est seulement lorsque les ressources sont correctement préparées que les réglages ultérieurs ont un sens.

Articles similaires

Voir tous les articles →

Commencez avec des artefacts IA persistants

Obtenez votre clé API et appelez des modèles d'image, de vidéo et d'audio via une API unique basée sur les tasks.

Lire la documentation de l'API