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
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.

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 :
- choisissez une image nette, de face ou presque de face, sans occlusion du visage ;
- évitez le contre-jour fort, les filtres lourds et les photos de groupe (le modèle ne peut pas déterminer qui aligner) ;
- 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 ;
- 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
stylevautAUTO,REALISTIC,FICTION, par défautAUTO. Pour un personnage réaliste, utilisezREALISTIC; pour une illustration stylisée,FICTION; en cas de doute, restez surAUTO. seedest 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.

Liste de vérification avant soumission
Vérifier chaque point selon le contrat permet d'écarter la plupart des échecs avant la soumission :
-
promptnon vide et ne dépassant pas 5000 caractères, avec un contenu décrivant une scène et non une instruction d'édition ; -
image_urlest un lien accessible anonymement commençant parhttp://ouhttps://; -
mask_urlest également accessible et possède le même rapport largeur/hauteur que l'image source ; -
reference_image_urlsest 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_speedutilisent les valeurs en majuscules listées dans le contrat) ; - si
seedest défini, vérifiez qu'il s'agit d'un entier entre 0 et 2147483647 ; - si
expand_promptest désactivé, vérifiez quepromptest 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 →-
Guide d'utilisation
Guide de démarrage avec gpt-6.2-sol : limites de capacité, intégration API et tarification par token
Points de décision et de pratique pour l'intégration par les équipes d'ingénierie
-
Guide d'utilisation
Guide de prise en main de gpt-6.2-astra : limites de capacités du modèle texte, points d'intégration et maîtrise des coûts
-
Guide d'utilisation
Guide de prise en main de Tripo H3.1 : trois modes d'entrée, paramètres et choix tarifaires
Décision d'intégration et maîtrise des coûts de la génération 3D pour les développeurs